Docker Pull Slow

Read the Pull Output Carefully

Docker pulls image layers separately and shows progress for each one. Some layers download quickly while one large layer crawls. Others may finish downloading and then spend time on local extraction — you will see the status change from "Downloading" to "Extracting." If network usage drops while disk activity rises, the bottleneck is CPU-bound layer decompression and extraction, not the internet connection. Distinguishing slow download from slow extraction is the first and most important step.

Common Docker Pull Bottlenecks

Docker Hub Rate Limiting

Docker Hub enforces pull rate limits based on authentication status. Anonymous pulls (no login) are limited to 100 pulls per 6 hours per IP address. Free authenticated accounts get 200 pulls per 6 hours. Paid Docker accounts have unlimited pulls. Rate limits are counted per image manifest request, not per layer, so pulling the same image multiple times counts each time.

When you hit the rate limit, Docker returns a clear error: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading. If you see this, authenticate with docker login and your credentials will be stored in ~/.docker/config.json. In CI environments, set DOCKER_USERNAME and DOCKER_PASSWORD as secrets and run docker login at the start of each job.

To check your current rate limit status before hitting it, you can request a Docker Hub token and query the rate limit headers:

TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
curl -I -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest

Look for the RateLimit-Remaining and RateLimit-Limit headers in the response.

Configuring a Registry Mirror

For teams or CI environments that pull frequently, configure a registry mirror in /etc/docker/daemon.json. This tells Docker to check a local or regional cache first before hitting Docker Hub directly:

{
  "registry-mirrors": ["https://mirror.example.com"]
}

Restart the Docker daemon after editing. Popular alternatives to Docker Hub include GitHub Container Registry (ghcr.io), Amazon ECR Public (public.ecr.aws), and Google Artifact Registry. All three bypass Docker Hub rate limits entirely when you push your own images there.

Fix 1: Compare Registries and Image Sizes

Pull a small public image and then the image that feels slow. If the small image is fast, your network is probably fine and the target image or registry path is the issue. Large base images, many layers, and missing caches are common causes.

docker pull alpine
docker pull ubuntu

Fix 2: Turn Off VPN or Corporate Proxy for One Test

Docker registry traffic can be slowed by VPN gateways, TLS inspection, malware scanning, and corporate proxies. If policy allows, test one pull off VPN. If it improves dramatically, ask your network team about registry allowlisting, split tunneling, or a local registry mirror that sits inside your corporate network.

Fix 3: Layer Caching — Download vs Extract

Docker's layer cache means that docker pull only downloads layers that are not already present on the local machine. If you run a build before the pull that uses the same base image, most layers will already exist and the pull will be nearly instant. In CI, cache the Docker layer store between runs using the --cache-from flag or a build cache export so that unchanged layers are never re-downloaded.

A layer that shows "Extracting" rather than "Downloading" is CPU-bound, not network-bound. Extraction decompresses the gzip-compressed tar archive onto disk. On slow disks or in resource-constrained Docker Desktop environments, extraction can take longer than the download. Check Docker Desktop's resource allocation (CPUs and memory) in Preferences → Resources if extraction is the consistent bottleneck.

Fix 4: Check Disk Space and Extraction

Docker needs space for compressed layers, extracted layers, image metadata, and containers. If the Docker data disk is nearly full, pulls can slow or fail. Check Docker's disk usage before deleting anything:

docker system df

If cleanup is needed, review what will be removed before running prune commands, especially on shared development machines. On Docker Desktop, the virtual disk has a maximum size configured in Preferences → Resources → Disk image size.

Fix 5: Use Smaller Images and Layer Hygiene

The best long-term fix is image hygiene. Use smaller base images (alpine instead of ubuntu when compatible), avoid putting build caches into final images with multi-stage builds, and keep frequently used base layers stable so they stay cached across builds. In CI, pulling a 3 GB image on every run is a workflow problem, not just a network problem. Move to a registry mirror and a well-structured Dockerfile that maximizes layer cache reuse.

Frequently Asked Questions

Why is docker pull slower than my speed test?

Docker pulls depend on registry routing, image layer size, TLS/proxy inspection, disk extraction speed, and registry rate limits. A speed test only measures your link to one nearby test server and does not reflect Docker Hub CDN routing or local extraction time.

Can DNS affect Docker pull speed?

Yes. Registry downloads are served through content networks, and DNS can influence which CDN endpoint you reach. A different reliable DNS resolver can sometimes route you to a closer or faster registry endpoint.

Is Docker Desktop the bottleneck?

Sometimes. Docker Desktop has to download, verify, extract, and store layers inside its virtualized environment. Low disk space, limited vCPUs, or a small memory allocation can make pulls appear network-slow when the real constraint is local resource contention.