← Guides

Pushing a Docker Image to AWS ECR

AWSDockerECRDevOps July 2026

Pushing a Docker Image to AWS ECR

Amazon Elastic Container Registry (ECR) is AWS’s managed Docker registry. This guide covers everything from creating a repository to pushing your image.

Prerequisites

  • Docker installed and running locally
  • AWS CLI installed and configured (aws configure)
  • An AWS account with ECR permissions

Step 1: Create an ECR Repository

aws ecr create-repository \
  --repository-name my-app \
  --region eu-west-2

Note the repositoryUri in the response — it follows this format:

<account-id>.dkr.ecr.<region>.amazonaws.com/<repository-name>

Step 2: Build Your Docker Image

If you are on Apple Silicon (M1/M2/M3), build for the linux/amd64 platform so the image runs on AWS:

docker buildx build --platform linux/amd64 -t my-app:1.0.0 .

On Intel/AMD:

docker build -t my-app:1.0.0 .

Step 3: Authenticate Docker to ECR

Run this command to get a temporary login token (valid for 12 hours):

aws ecr get-login-password --region eu-west-2 \
  | docker login \
    --username AWS \
    --password-stdin \
    <account-id>.dkr.ecr.eu-west-2.amazonaws.com

You should see:

Login Succeeded

Step 4: Tag the Image with the ECR URI

Docker needs the full ECR URI as the image name before it can push:

docker tag my-app:1.0.0 \
  <account-id>.dkr.ecr.eu-west-2.amazonaws.com/my-app:1.0.0

Step 5: Push the Image

docker push <account-id>.dkr.ecr.eu-west-2.amazonaws.com/my-app:1.0.0

Docker uploads each layer individually. Once complete, the image is available in ECR.

Step 6: Verify the Push

Check the image is in ECR:

aws ecr list-images \
  --repository-name my-app \
  --region eu-west-2

Or open the AWS Console → ECR → your repository → Images.

Troubleshooting

no basic auth credentials — the login token expired or wasn’t set. Re-run Step 3.

exec format error on the instance — the image was built for the wrong platform. Rebuild with --platform linux/amd64.

repository does not exist — the repository name in your tag doesn’t match what you created in Step 1. Check with:

aws ecr describe-repositories --region eu-west-2