Docker Hub Pull Rate Limits#

Docker Hub enforces pull rate limits on a 6-hour rolling window based on authentication status 1:

When the limit is exceeded, Docker returns HTTP 429 with body You have reached your pull rate limit… 2. A separate abuse rate limit (also 429 Too Many Requests, but without that body) applies to all users regardless of plan 1.

Note on official documentation: The two canonical Docker docs pages (pull usage and usage & limits) have at times shown contradictory anonymous-pull quotas. Teach the workaround, not the specific number—verify any cited figure on the day it is written 3.

You can inspect your current remaining quota without consuming a pull using a HEAD request against registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest with a bearer token, and examining the ratelimit-limit / ratelimit-remaining response headers 2.

Why This Matters in a Classroom#

In a university setting, all students share a single campus public IP. Anonymous pulls exhaust the 100-pull quota almost immediately once a cohort starts a practical session. The resulting toomanyrequests error is opaque to beginners 3.

The course currently has no teaching on pull rate limits and docker login does not appear in any chapter. The proxy chapter describes the phenomenon as a "blacklist" — this is incorrect terminology; Docker Hub applies rate limiting, not IP banning.

Workarounds (Ranked by Practicality)#

1. docker login before the session (fastest)

Authenticating raises the per-user quota from 100 to 200 and, more importantly, counts pulls against the user's identity rather than the shared campus IP:

docker login # prompts for Docker Hub username + password/token

For Docker Engine (non-Desktop), use docker login from a terminal. For CI environments, see platform-specific instructions 2.

2. Pre-pull images at the start of the session

Pull all images needed for the lab before students begin, so subsequent docker run calls are satisfied from the local cache without hitting Hub.

3. Configure a registry mirror (campus-level fix)

The university provides a caching proxy at cache-ili.univ-artois.fr. Add it to /etc/docker/daemon.json:

{
  "registry-mirrors": ["http://cache-ili.univ-artois.fr:80/proxy_cache/"],
  "insecure-registries": ["cache-ili.univ-artois.fr:80"]
}

Then restart Docker: sudo systemctl restart docker. After this, standard commands like docker pull ubuntu:22.04 route transparently through the cache 4.

⚠️ Unverified configuration: The registry-mirrors entry above includes a URL path (/proxy_cache/), which deviates from Docker's documented form (schema + host only). Docker's ValidateMirror function accepts the path without error, so Docker will start — but implicit pulls may silently fall back to Docker Hub if the cache server does not expose the v2 Registry API under that path. Test on campus before the first session. If it fails, try "http://cache-ili.univ-artois.fr:80" (no path) in registry-mirrors, and use the explicit path only in direct docker pull commands 5.

Explicit pulls using the full cache path always work regardless of the registry-mirrors config:

docker pull cache-ili.univ-artois.fr:80/proxy_cache/library/ubuntu:22.04

6

Documentation Gaps and Known Issues#

Three open issues track documentation problems in proxy.adoc:

The security-production chapter also references Docker Hub pull limits briefly in the context of private registries as a motivation for hosting images privately 10.

Key Source Files#