Amazon ECR limits and quotas
An ECR image layer can be up to 52,000 MiB, a repository can hold 100,000 images and a registry 100,000 repositories per Region (both adjustable). Pulls are governed by API rates: 2,000 BatchGetImage and 3,000 GetDownloadUrlForLayer requests per second per Region by default, while pushes are limited by PutImage at 10 per second and layer uploads at 100 to 500 per second; these rates are adjustable. Lifecycle policies are limited to 50 rules and basic scanning to one scan per image per 24 hours.
Storage and size quotas
| Quota | Default | Adjustable |
|---|---|---|
| Registered repositories per Region | 100,000 | Yes |
| Images per repository | 100,000 | Yes |
| Maximum layer size | 52,000 MiB | No |
| Layer part size (direct API uploads) | 5 MiB to 10 MiB | No |
| Layer parts per upload | 4,200 | No |
| Tags per image | 1,000 | No |
| Lifecycle policy length | 30,720 characters | No |
| Rules per lifecycle policy | 50 | No |
| Rules per replication configuration | 25 | No |
| Pull through cache rules per registry | 50 | No |
The layer part limits only matter if you call the ECR upload APIs yourself; Docker, BuildKit and other clients handle chunking. Container images used by Lambda are separately limited to 10 GB uncompressed by Lambda.
API rate quotas (per account per Region)
| API | Default | Used when |
|---|---|---|
| GetAuthorizationToken | 500/s | Every docker login / credential helper refresh |
| BatchGetImage | 2,000/s | Pulling a manifest (once per image pull) |
| GetDownloadUrlForLayer | 3,000/s | Each layer not already cached on the host |
| BatchCheckLayerAvailability | 1,000/s | Push: checking which layers exist |
| InitiateLayerUpload / CompleteLayerUpload | 100/s each | Push: once per new layer |
| UploadLayerPart | 500/s | Push: each chunk of a new layer |
| PutImage | 10/s | Push: once per image manifest |
| Basic scans | 100,000 images per 24 hours; 1 scan per image per 24 hours | Scan on push and manual scans |
All the rate quotas above are adjustable. Throttled calls return ThrottlingException (Rate exceeded), which container runtimes show as a failed pull; on ECS that becomes CannotPullContainerError (see the fix).
When the rates bite
- Large scale-outs: 1,000 new nodes or tasks pulling an image with 20 layers is 20,000 layer URL requests. Spread over a minute that's fine; all in a few seconds it throttles. Fewer, larger layers and pre-pulled AMIs or warm pools help.
- CI pipelines that push many images in parallel can hit PutImage at 10 per second. Serialise pushes or request an increase.
- Credential refreshes: some tooling calls GetAuthorizationToken on every pull; the token is valid for 12 hours, so cache it.
# Image count in a repository
aws ecr describe-images --repository-name orders-api --query 'length(imageDetails)'
# Largest images by compressed size
aws ecr describe-images --repository-name orders-api \
--query 'reverse(sort_by(imageDetails,&imageSizeInBytes))[:5].[imageTags[0],imageSizeInBytes]' --output table
aws service-quotas list-service-quotas --service-code ecr --query "Quotas[].[QuotaName,QuotaCode,Value]" --output tableKeeping repositories within limits
Add a lifecycle policy to every repository: expire untagged images after a few days and keep only the last N tagged images. This keeps you far from 100,000 images, reduces storage cost, and makes describe-images faster. Fifty rules per policy is plenty if you group by tag prefix.
Questions
What is the maximum image size in ECR?
ECR limits each layer to 52,000 MiB rather than the image as a whole. Services that run images may have their own limits, such as 10 GB uncompressed for Lambda container images.
How many images can an ECR repository hold?
100,000 images per repository by default. The quota is adjustable, but a lifecycle policy is usually the better answer.
Does ECR have pull rate limits?
Yes. Pulls are limited by API rates such as 2,000 BatchGetImage and 3,000 GetDownloadUrlForLayer requests per second per Region by default, both adjustable.
Registry throttling usually appears as tasks or pods stuck pulling images during a large scale-out. CloudConsole, a phone app for AWS, is being built to show those failed task events and alarms on your phone.
About the app → · Download on the App Store