How to Push Docker Image to AWS ECR Easily

To push an image to AWS ECR, first authenticate your Docker client with aws ecr get-login-password. Then tag your local image with the ECR repository URI using docker tag, and finally push it using docker push.

Syntax

Here are the main commands to push an image to ECR:

• aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<region>.amazonaws.com: Logs Docker into your ECR registry.
• docker tag <local-image> <aws_account_id>.dkr.ecr.<region>.amazonaws.com/<repository-name>:<tag>: Tags your local image with the ECR repository URI.
• docker push <aws_account_id>.dkr.ecr.<region>.amazonaws.com/<repository-name>:<tag>: Pushes the tagged image to ECR.

bash

aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<region>.amazonaws.com

docker tag <local-image> <aws_account_id>.dkr.ecr.<region>.amazonaws.com/<repository-name>:<tag>

docker push <aws_account_id>.dkr.ecr.<region>.amazonaws.com/<repository-name>:<tag>

Example

This example shows how to push a Docker image named my-app with tag v1 to an ECR repository called my-repo in the us-west-2 region.

bash

aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-west-2.amazonaws.com

docker tag my-app:latest 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repo:v1

docker push 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repo:v1

Output

Login Succeeded
The push refers to repository [123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repo]
...
latest: digest: sha256:abcdef1234567890 size: 1234

Common Pitfalls

• Not authenticating Docker with ECR before pushing causes permission errors.
• Using incorrect region or AWS account ID in the repository URI leads to push failures.
• Forgetting to tag the local image with the full ECR URI results in pushing to the wrong place.
• Not having the ECR repository created beforehand will cause push errors.

bash

Wrong way:

# Missing login step

docker tag my-app:latest 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repo:v1

docker push 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repo:v1

Right way:

aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-west-2.amazonaws.com

docker tag my-app:latest 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repo:v1

docker push 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repo:v1

Quick Reference

Remember these quick tips:

• Always run aws ecr get-login-password to authenticate before pushing.
• Tag images with the full ECR URI including region and account ID.
• Create your ECR repository in AWS Console or CLI before pushing.
• Use consistent tags to manage image versions.

Key Takeaways

Authenticate Docker to ECR using AWS CLI before pushing images.

Tag your local Docker image with the full ECR repository URI.

Push the tagged image to ECR using the docker push command.

Ensure the ECR repository exists before pushing images.

Use correct AWS region and account ID in all commands.