docker / pull-rate-limit-exceeded

docker pull rate limit exceeded — how to fix

Quick Answer

# Authenticate to Docker Hub first
docker login

# Then retry the pull
docker pull ubuntu:24.04

# In CI, use a token-backed login instead of anonymous pulls
echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin

When this happens

toomanyrequests: You have reached your pull rate limit.
You may increase the limit by authenticating and upgrading:
https://www.docker.com/increase-rate-limit

Docker Hub limits anonymous pulls per IP address. This happens often in CI, shared office networks, and cloud runners where many machines share one outbound IP.

Ways to reduce pull pressure

Use an authenticated pull in CI

# GitHub Actions / CI example
echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
docker pull node:20-alpine

Mirror images to another registry

If the same base images are pulled repeatedly, mirror them to GHCR, ECR, GCR, or your internal registry and pull from there instead.

# Example: retag and push to another registry
docker pull node:20-alpine
docker tag node:20-alpine ghcr.io/your-org/node:20-alpine
docker push ghcr.io/your-org/node:20-alpine

Pin exact tags and cache layers

# Better than floating latest in CI
FROM node:20.19.2-alpine3.21

# Also enable your CI provider's Docker layer cache if available

Shared IPs can trigger the limit faster

# Check whether you are already logged in
docker info | grep -i username

# If blank, you are pulling anonymously

Related