Skip to main content
This guide demonstrates how to work with Amazon Elastic Container Registry (ECR): create a repository in the AWS Console, authenticate Docker to ECR, push a Docker image, and pull that image to run a container. Follow the steps in order and replace the example AWS account ID, region, and repository name with your own.

​
1) Create a repository in the AWS Console

In the AWS Management Console search for “ECR” and choose Create repository (or go to Repositories → Create repository). During creation you can configure visibility, immutability, image scan on push, and KMS encryption.
An AWS Management Console screenshot of the ECR "Create repository" page. It shows image scan settings (a deprecation warning and scan-on-push disabled), KMS encryption disabled, and a "Create repository" button.
Use the following table to choose repository visibility:
Repository visibility cannot be changed after creation. Choose Private or Public carefully before creating the repository.
After clicking Create repository, the new repository (for example, ecrdemo) appears in the list. It initially has no images until you push one.

​
2) Authenticate Docker to ECR

ECR authentication uses the AWS CLI to generate a short-lived Docker login token. Run the following command (example uses region us-west-1 and account 841860927337):
Authentication prerequisites:
  • Install and configure the AWS CLI and run aws configure with credentials that have ECR permissions, or
  • If running on EC2/ECS/EKS, attach an IAM role with appropriate ECR permissions to the instance, task, or node (preferred for AWS-hosted compute).
If you see “Your password will be stored unencrypted in /home/…/.docker/config.json”, configure the Docker credential helper or the Amazon ECR credential helper to avoid storing plaintext credentials. See the Docker documentation and the Amazon ECR credential helper docs for setup instructions.
Example of the login command output:

​
3) Build, tag, and push a Docker image to ECR

Replace the account ID, region, and repository name in these commands.
Example local build, tag, and inspection:
When you run docker push, Docker uploads each layer and prints a digest for the image:
Refresh the repository page in the Console to see the newly pushed image, its tag(s), and push timestamp.

​
4) Pull and run the image from ECR

To confirm another host can pull the image from ECR, remove the local ECR-tagged image and run a container using the full ECR URI. Docker will pull the image if it is not found locally.
Example output showing Docker pulling the image and the application starting:
You can then verify the application locally (example HTML response returned by the app):

​
5) Repository naming and where to use the full image URI

Remember the full image name format used to push and pull from ECR: <aws-account-id>.dkr.ecr.<region>.amazonaws.com/<repository-name>:<tag> Example: 841860927337.dkr.ecr.us-west-1.amazonaws.com/ecrdemo:latest Use this full URI in:
  • Docker CLI
  • Amazon ECS task definitions
  • Kubernetes manifests (EKS)
  • Any other container orchestration platform that pulls from ECR

​
Quick reference table

​
Permissions and best practices

  • Ensure any machine or service that pulls images has valid AWS credentials or an attached IAM role with ECR read permissions.
  • For AWS-hosted compute (EC2, ECS, EKS), prefer using IAM roles with the minimum required ECR permissions rather than embedding long-lived access keys.
  • Consider enabling image scan on push and using image tag immutability to improve security and traceability.
That covers the basics of creating an ECR repository, authenticating Docker, pushing an image, and pulling it to run a container.

Watch Video