Introduction

Untagged images in Amazon ECR usually appear after you retag or replace images and the old manifest is left behind without a human-friendly tag. They still consume storage, so cleaning them up is a normal maintenance task. You can delete them manually with the AWS CLI, but in most repositories the better long-term answer is an ECR lifecycle policy.

What "Untagged" Means in ECR

An untagged image in ECR still has an image digest. It is not anonymous or broken. It simply no longer has a tag such as latest, v1.4.2, or build-123 pointing to it.

That distinction matters because deletion commands usually identify the image by digest, not by tag.

A quick way to inspect untagged images in a repository is:

aws ecr list-images \
  --repository-name my-app \
  --filter tagStatus=UNTAGGED

This returns image identifiers that typically contain imageDigest values.

One-Off Deletion With the AWS CLI

If you want to clean up a small set of untagged images immediately, use batch-delete-image with one or more digests.

aws ecr batch-delete-image \
  --repository-name my-app \
  --image-ids imageDigest=sha256:1111111111111111111111111111111111111111111111111111111111111111

You can pass multiple digests in the same command:

1aws ecr batch-delete-image \
2  --repository-name my-app \
3  --image-ids \
4    imageDigest=sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
5    imageDigest=sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

This is fine for occasional cleanup, but it is not the most maintainable solution if untagged images accumulate regularly.

The Better Long-Term Option: Lifecycle Policies

ECR supports lifecycle policies that automatically expire images that match rules such as tagStatus=untagged. This is usually the right answer for build pipelines that continuously push replacement images.

Example lifecycle policy document:

1{
2  "rules": [
3    {
4      "rulePriority": 1,
5      "description": "Delete untagged images after 7 days",
6      "selection": {
7        "tagStatus": "untagged",
8        "countType": "sinceImagePushed",
9        "countUnit": "days",
10        "countNumber": 7
11      },
12      "action": {
13        "type": "expire"
14      }
15    }
16  ]
17}

Apply it with:

aws ecr put-lifecycle-policy \
  --repository-name my-app \
  --lifecycle-policy-text file://lifecycle-policy.json

This approach is safer than constant manual deletion because it makes retention rules explicit and repeatable.

When to Delete Immediately Versus Retain Briefly

Immediate deletion is reasonable when:

• a repository is only a cache
• storage is growing unexpectedly
• the untagged images are known build leftovers

A short retention window is better when:

• rollbacks may still need recent digests
• build pipelines retag images in stages
• other systems briefly refer to digests rather than tags

Many teams keep untagged images for a few days rather than deleting them the moment they lose a tag.

Permissions You Need

The IAM principal performing cleanup needs the relevant ECR permissions. For manual deletion, the key permission is ecr:BatchDeleteImage. For policy-based cleanup, you also need lifecycle policy permissions such as ecr:PutLifecyclePolicy.

If deletion fails with an access error, fix IAM before changing the command syntax.

Repository Hygiene Matters

A good ECR cleanup policy pairs well with disciplined tagging. If every CI run overwrites latest and also pushes an immutable tag such as a commit SHA, then you have a clear rollback path and can delete untagged leftovers more aggressively.

If your process depends heavily on untracked transient tags, cleanup becomes riskier because an apparently expendable digest may still matter operationally.

Common Pitfalls

The most common mistake is assuming untagged means unused. In ECR, the image can still exist by digest and may still be relevant for rollback or debugging.

Another mistake is trying to delete by tag when the image no longer has one. Untagged cleanup is usually digest-based.

Developers also often script repeated manual cleanup when a lifecycle policy would solve the recurring problem more cleanly.

Finally, do not apply aggressive deletion blindly in repositories shared by multiple environments. Make sure your tagging and deployment conventions support that retention policy first.

Summary

• Untagged ECR images still exist by digest and still consume storage.
• Use list-images with tagStatus=UNTAGGED to inspect them.
• Use batch-delete-image for one-off cleanup by digest.
• Prefer ECR lifecycle policies for recurring automated cleanup.
• Set retention rules that match your rollback and deployment needs.