Amazon ECR Explained: Private vs Public, Push/Pull, IAM, and Scanning

Simple explanation

ECR is AWS’s place to store container images so services like ECS, EKS, Lambda, and App Runner can pull them. Think of it as a private warehouse for the packaged software bundles your workloads run from.

The five terms in full:

• Registry: the top-level storage system. Every AWS account gets one private ECR registry, identified by your account ID and region: 123456789012.dkr.ecr.us-east-1.amazonaws.com.
• Repository: a named slot inside your registry for one application or image family, such as my-app or api-server. You create repositories and push images into them.
• Image: the packaged, immutable bundle your container runs from. An image includes your application code, runtime, libraries, and dependencies. See Container Images in AWS for a deeper look at how images are built and layered.
• Tag: a human-readable label pointing to a specific image, such as 1.2.3, latest, or abc1234 (a Git commit SHA). Tags are mutable by default. The same tag can be reassigned to a different image.
• Digest: an immutable SHA256 fingerprint of the exact image content: sha256:abc123…. If you need to guarantee you are running exactly the same bits every time, not just the same tag, reference the image by digest.

Full image reference format: account-id.dkr.ecr.region.amazonaws.com/repository-name:tag

What Amazon ECR is

ECR is a fully managed registry. AWS handles availability, replication, and storage. You do not run any registry infrastructure. You create repositories, push images, and reference them by URI. AWS compute services pull from ECR automatically using their IAM execution roles.

Teams use ECR for AWS workloads rather than an external registry for several concrete reasons:

• IAM-based access. No separate registry account or password file. An ECS task, Lambda function, or EKS node pulls from ECR using its IAM role. You control access the same way you control any other AWS resource.
• Regional proximity. ECR repositories live in a specific AWS region. Pulling from a repo in the same region as your workload is fast, and there are no data transfer fees for pulls within the same region.
• Image scanning. Basic vulnerability scanning is included at no extra cost. Enhanced scanning via Amazon Inspector adds continuous scanning and language-level dependency checks.
• Lifecycle policies. Automatically expire old images to keep storage costs under control. Without this, a busy CI/CD pipeline accumulates thousands of images that are never cleaned up.
• No pull rate limits. Docker Hub throttles unauthenticated and free-tier pulls. ECR has no equivalent limits for AWS traffic pulling from within the same region.

How ECR works

The end-to-end flow from build to deployed workload:

1. Build the image. A developer or CI/CD pipeline builds a container image from a Dockerfile. If you use AWS CodeBuild to build Docker images, the build runs inside AWS and pushes directly to ECR without leaving the AWS network.
2. Tag the image. Assign a version tag that identifies this specific build: a semantic version (1.2.3) or a Git commit SHA (abc1234). Tagging with latest alone loses rollback ability.
3. Authenticate Docker to ECR. The build environment runs aws ecr get-login-password to get a short-lived token, then passes it to docker login. This token is valid for 12 hours.
4. Push the image. docker push sends image layers to your ECR repository. Only changed layers are uploaded. Unchanged layers are stored once and reused across images.
5. AWS service pulls the image. When ECS launches a task, EKS schedules a pod, Lambda initialises a container function, or App Runner deploys a service, it fetches the image from ECR using the service’s IAM execution role.
6. ECR scans the image. If scan-on-push is enabled, ECR checks the image against known vulnerability databases immediately after the push completes.
7. Lifecycle rules expire old images. Lifecycle policies run periodically and delete images that match expiry criteria. For example: untagged images older than 7 days, or more than 10 release-tagged images in a repository.

When to use Amazon ECR

Use ECR when:

• Running containers on ECS or EKS. ECR is the natural image store for both. Task definitions and pod specs reference ECR image URIs directly. The service’s IAM role handles authentication automatically. See EKS vs ECS in AWS if you are still deciding between the two.
• Deploying Lambda container images. Lambda functions packaged as container images must use ECR as their image source. If your function exceeds the zip deployment size limit or needs a custom runtime, Lambda container images pull from ECR at cold start.
• Deploying to App Runner. AWS App Runner can pull container images from ECR and deploy them as managed web services with no infrastructure to manage.
• Keeping CI/CD builds inside AWS. When your pipeline runs inside AWS (CodeBuild, GitHub Actions with OIDC), pushing to ECR instead of Docker Hub avoids pull rate limits and keeps image traffic inside the AWS network. See CI/CD Pipelines for Amazon ECS for an end-to-end example.
• Sharing public base images. ECR Public lets you publish open-source or publicly shared images without a Docker Hub account. AWS uses ECR Public for its own official images.
• Enforcing access control on images. For proprietary application images, ECR’s IAM-based access means only the identities you explicitly permit can pull them.

If you are still deciding which AWS compute service to run your containers on, Choosing Between EC2, Lambda, and Containers in AWS walks through the trade-offs.

ECR Private vs ECR Public

Most teams use private ECR for their application images and ECR Public only for open-source projects or base images they want to share externally.

Amazon ECR vs Docker Hub

Most AWS teams pull well-known base images (such as ubuntu, node, or python) from Docker Hub or ECR Public during development, build their own application image on top, and store that in private ECR.

Creating a repository

Create a private ECR repository with the AWS CLI:

aws ecr create-repository \
  --repository-name my-app \
  --image-scanning-configuration scanOnPush=true \
  --encryption-configuration encryptionType=AES256 \
  --region us-east-1

The command returns the full repository URI you will use for all push and pull operations:

{
    "repository": {
        "repositoryArn": "arn:aws:ecr:us-east-1:123456789012:repository/my-app",
        "registryId": "123456789012",
        "repositoryName": "my-app",
        "repositoryUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app"
    }
}

scanOnPush=true enables automatic basic scanning on every push. encryptionType=AES256 encrypts images at rest using an AWS-managed key. For customer-managed KMS keys, use encryptionType=KMS and specify a key ARN.

Pushing and pulling images

Authenticate Docker to ECR

The AWS CLI generates the token and pipes it directly to Docker:

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

Tag and push

# Build the image
docker build -t my-app:1.2.3 .

# Tag with the full ECR repository URI
docker tag my-app:1.2.3 \
  123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:1.2.3

# Push
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:1.2.3

Version tags, latest, and digests

The latest tag is convenient but problematic for production deployments. Because it is mutable, two separate deploys using latest may actually run different code. Use a specific version tag (a semantic version like 1.2.3, or a Git commit SHA like abc1234) so you can trace exactly which build is running and roll back to a known-good version if needed.

If you need an even stronger guarantee, reference the image by its SHA256 digest: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app@sha256:abc123…. Digests are immutable. No one can change what they point to. Enabling tag immutability on the repository is the more practical production pattern and is covered in the ECR Best Practices for Production guide.

Pull an image

docker pull 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:1.2.3

List images in a repository

aws ecr list-images \
  --repository-name my-app \
  --query "imageIds[*].[imageTag,imageDigest]" \
  --output table

Image scanning

ECR scans images for known vulnerabilities (CVEs) in two modes:

Basic scanning (free)

Basic scanning checks OS package vulnerabilities against standard CVE databases. It runs automatically on push when enabled, or on demand. Results are categorised as CRITICAL, HIGH, MEDIUM, LOW, and INFORMATIONAL. Enable it on every repository. It is free and requires no ongoing configuration beyond turning it on.

# Trigger a manual scan (if not using scan-on-push)
aws ecr start-image-scan \
  --repository-name my-app \
  --image-id imageTag=1.2.3

# View scan results
aws ecr describe-image-scan-findings \
  --repository-name my-app \
  --image-id imageTag=1.2.3

Enhanced scanning (paid, via Amazon Inspector)

Enhanced scanning uses Amazon Inspector and goes further than basic scanning in two ways:

• It checks both OS packages and application-level dependencies: Python pip packages, npm packages, Java libraries, and others.
• It scans continuously. If a new CVE is published against a library your image uses, you are notified without pushing a new image.

Enhanced scanning is a paid feature. Basic scanning is the right starting point for most teams.

IAM access control

ECR access is controlled by two distinct types of IAM policy. Understanding which to use matters. See IAM Roles Explained for a primer on how IAM roles and policies work in AWS.

IAM identity policies (attached to roles or users)

These are the most common case. Attach an identity policy to an IAM role to grant it permission to push or pull ECR images: for example, an ECS task execution role, a Lambda execution role, or a CI/CD pipeline role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["ecr:GetAuthorizationToken"],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "arn:aws:ecr:us-east-1:123456789012:repository/my-app"
    }
  ]
}

The AmazonEC2ContainerRegistryReadOnly AWS managed policy is a convenient shortcut for pull-only access. For the difference between AWS managed policies and customer-managed policies, see Managed vs Customer Managed Policies.

Repository resource policies (cross-account access)

A repository policy is attached directly to a specific ECR repository and grants access to principals in other AWS accounts. Use this when a workload in Account B needs to pull images stored in Account A’s ECR registry. Identity policies alone cannot grant cross-account ECR access.

aws ecr set-repository-policy \
  --repository-name my-app \
  --policy-text '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::987654321098:root"},
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ]
    }]
  }'

Integration with AWS compute services

AWS compute services authenticate to ECR automatically using the service’s IAM execution role. You provide the image URI and ECR handles the credential exchange.

For ECS and Lambda, attaching AmazonEC2ContainerRegistryReadOnly to the execution role covers all required pull actions. For EKS, the same policy is attached to the EC2 instance profile on the node group.