How to Use Amazon ECR: Managing Container Images with AWS CLI

When building and operating containerized applications, you need a place to store your Docker images. If you're using AWS, one great answer is Amazon ECR (Elastic Container Registry) — a fully managed container image registry that integrates seamlessly with AWS services like ECS and EKS. In this article, we'll walk through how ECR works and how to create a repository, push, and pull images using the AWS CLI.

What is Amazon ECR?

Amazon ECR is a container image registry service for storing and managing Docker images and OCI (Open Container Initiative)-compliant artifacts. Unlike public registries such as Docker Hub, ECR provides private repositories by default. Access is controlled through AWS IAM, giving you fine-grained permission management.

Images stored in ECR can be referenced directly by AWS compute services including Amazon ECS, EKS, AWS Batch, and App Runner. Since there are no data transfer charges within the same region, ECR is the natural choice when running containers on AWS.

What is Amazon Elastic Container Registry? - Amazon ECR

Amazon ECR is an AWS managed container image registry service.

docs.aws.amazon.com

Core ECR Concepts

Let's clarify a few terms before you get started.

Term	Description
Registry	The top-level container for images. One registry is created per AWS account.
Repository	A grouping unit for images. You give it a name like myapp/frontend.
Image tag	A label that identifies a specific image within a repository (e.g., latest, v1.0.0).
Image digest	A hash of the image. More unique than a tag and serves as an immutable identifier.

ECR uses the following URI format. You specify this URI when referencing an image during deployment.

{account-id}.dkr.ecr.{region}.amazonaws.com/{repository-name}:{tag}

Public vs. Private Registries

ECR offers two types of registries: private and public. Choose based on your use case.

	Private Registry	Public Registry
Access	Requires IAM authentication	Anyone can pull without authentication
Hostname	{account-id}.dkr.ecr.{region}.amazonaws.com	public.ecr.aws
Primary use	Internal / project image management	Distributing OSS or public images
Pricing	Charged by storage and data transfer	Free up to a certain limit

Use private registries for internal application images and public registries for distributing open-source tools or base images. This article focuses on private registries.

Security Features

ECR includes several features to strengthen image security. Make sure to review these settings for production environments.

Feature	Description
Image scanning	Detects OS package vulnerabilities on push or on demand
Image encryption	Encrypts images in the repository using AWS KMS
Tag immutability	Prevents overwriting a tag with a new push, ensuring image integrity
VPC endpoint	Access ECR from within a VPC without going through the internet

Scan images for software vulnerabilities in Amazon ECR - Amazon ECR

Use Amazon ECR image scanning to help identify software vulnerabilities in your container images.

docs.aws.amazon.com

Using ECR with the AWS CLI

Let's walk through everything from creating a repository to pushing and pulling images using the AWS CLI.

Create a Repository

Use the create-repository command to create a repository. Here's what the options do:

• --image-scanning-configuration scanOnPush=true: Automatically runs an image scan on every push
• --image-tag-mutability IMMUTABLE: Prevents overwriting images with the same tag

❯ aws ecr create-repository \
    --repository-name myapp/frontend \
    --image-scanning-configuration scanOnPush=true \
    --image-tag-mutability IMMUTABLE
{
    "repository": {
        "repositoryArn": "arn:aws:ecr:us-east-1:123456789012:repository/myapp/frontend",
        "registryId": "123456789012",
        "repositoryName": "myapp/frontend",
        "repositoryUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp/frontend",
        "createdAt": "2026-05-14T18:17:26.708000+09:00",
        "imageTagMutability": "IMMUTABLE",
        "imageScanningConfiguration": {
            "scanOnPush": true
        },
        "encryptionConfiguration": {
            "encryptionType": "AES256"
        }
    }
}

You'll use the repositoryUri shown here for push and pull operations.

Authenticate with ECR

To connect the Docker client to ECR, you need to obtain an authentication token and log in. Use the get-login-password command to retrieve the token and pass it to docker login.

❯ aws ecr get-login-password | \
    docker login --username AWS --password-stdin \
    123456789012.dkr.ecr.us-east-1.amazonaws.com
Login Succeeded

Once you see Login Succeeded, you're authenticated. The token expires after 12 hours, so re-authenticate each time you run this in a CI/CD pipeline or similar recurring workflow.

Pull an Image and Tag It

Let's pull nginx:alpine from Docker Hub for testing purposes.

❯ docker pull nginx:alpine

Tag the pulled image with your ECR URI. The original image remains unchanged — you're just adding an alias that points to the same layers.

❯ docker tag nginx:alpine \
    123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp/frontend:v1.0.0

Push the Image

Push the tagged image to ECR. If you set scanOnPush=true, an image scan runs automatically after the push completes.

❯ docker push \
    123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp/frontend:v1.0.0

After the push, you can list the images in the repository via the CLI.

❯ aws ecr describe-images \
    --repository-name myapp/frontend
{
    "imageDetails": [
        {
            "registryId": "123456789012",
            "repositoryName": "myapp/frontend",
            "imageDigest": "sha256:abc123def456...",
            "imageTags": [
                "v1.0.0"
            ],
            "imageSizeInBytes": 26092648,
            "imagePushedAt": "2026-05-14T18:22:58.657000+09:00",
            "imageManifestMediaType": "application/vnd.docker.distribution.manifest.v2+json",
            "artifactMediaType": "application/vnd.docker.container.image.v1+json",
            "imageStatus": "ACTIVE"
        }
    ]
}

Pull the Image

To pull an ECR image from another environment, authenticate first and then run docker pull. When pulling from ECS or EKS, you can grant permissions via a task role or node IAM role for automatic authentication — but for local or CI environments, you'll need to authenticate manually.

❯ aws ecr get-login-password | \
    docker login --username AWS --password-stdin \
    123456789012.dkr.ecr.us-east-1.amazonaws.com
Login Succeeded

Once authenticated, pull the image.

❯ docker pull \
    123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp/frontend:v1.0.0

Auto-Delete Old Images with Lifecycle Policies

As images accumulate in ECR, storage costs can grow. Lifecycle policies let you automatically delete images that match certain conditions.

Policies are defined as rules. The example below sets a rule to delete untagged images oldest-first when there are more than 5.

❯ cat << 'EOF' > lifecycle-policy.json
{
  "rules": [
    {
      "rulePriority": 1,
      "description": "Keep only 5 untagged images",
      "selection": {
        "tagStatus": "untagged",
        "countType": "imageCountMoreThan",
        "countNumber": 5
      },
      "action": {
        "type": "expire"
      }
    }
  ]
}
EOF

❯ aws ecr put-lifecycle-policy \
    --repository-name myapp/frontend \
    --lifecycle-policy-text file://lifecycle-policy.json
{
    "registryId": "123456789012",
    "repositoryName": "myapp/frontend",
    "lifecyclePolicyText": "{\"rules\":[{\"rulePriority\":1,\"description\":\"Keep only 5 untagged images\",\"selection\":{\"tagStatus\":\"untagged\",\"countType\":\"imageCountMoreThan\",\"countNumber\":5},\"action\":{\"type\":\"expire\"}}]}"
}

Automate the cleanup of images by using lifecycle policies in Amazon ECR - Amazon ECR

Use lifecycle policies rules to automatically clean up your repositories.

docs.aws.amazon.com

Clean Up Resources

To delete the repository, use the delete-repository command. The --force flag is required if images still exist in the repository.

❯ aws ecr delete-repository \
    --repository-name myapp/frontend \
    --force
{
    "repository": {
        "repositoryArn": "arn:aws:ecr:us-east-1:123456789012:repository/myapp/frontend",
        "registryId": "123456789012",
        "repositoryName": "myapp/frontend",
        "repositoryUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp/frontend",
        "createdAt": "2026-05-14T18:17:26.708000+09:00",
        "imageTagMutability": "IMMUTABLE"
    }
}

Summary

• ECR is a fully managed container image registry from AWS with fine-grained access control through IAM
• It integrates seamlessly with AWS compute services like ECS, EKS, and App Runner, with no data transfer charges within the same region
• Authenticate the Docker client with an ECR token to push and pull images
• Enable tag immutability to prevent tag overwrites, and enable scan-on-push to automatically detect vulnerabilities
• Set lifecycle policies to auto-delete old images and keep storage costs down