docker pull: Usage, Options & Rate-Limit Errors

Download an image from a registry - and beat the Docker Hub rate limit in CI.

docker pull downloads an image (or a specific tag/digest) from a registry to the local daemon. This page covers the flags and the registry errors CI hits most.

What it does

docker pull fetches image layers from a registry. Without a registry prefix it defaults to Docker Hub (docker.io). Without a tag it pulls :latest.

Common usage

Terminal

docker pull nginx:1.27
docker pull ghcr.io/owner/image:sha-abc123
docker pull --platform linux/arm64 alpine:3.20
docker pull alpine@sha256:abcd...   # pin by digest

Common errors in CI

The classic CI failure is "toomanyrequests: You have reached your pull rate limit" from Docker Hub, which rate-limits anonymous and free pulls per IP. Authenticate with docker login before pulling, mirror the image to GHCR or ECR, or use a pull-through cache. A second error: "no matching manifest for linux/amd64 in the manifest list entries" - the image lacks your platform; pass --platform or pick a multi-arch tag.

Related guides

Docker "toomanyrequests: rate limit exceeded" - Fix Docker Hub Pull LimitsFix Docker Hub "toomanyrequests: You have reached your pull rate limit" in CI by authenticating, caching imag… docker login: Authenticate to a Registry in CIHow docker login works: authenticating to Docker Hub, GHCR, or ECR with a token from stdin, and the auth erro… docker push: Usage, Options & Auth Errors in CIHow docker push works: uploading a tagged image to a registry, naming requirements, and the denied/unauthoriz… docker manifest: Inspect & Build Multi-Arch ListsHow docker manifest works: inspecting and creating multi-architecture manifest lists, the experimental flag,…