How do you keep building when Docker Hub is down? Use a pull-through cache

Run a registry as a pull-through cache for Docker Hub and point your Docker daemons at it. Images your builds have pulled before are then served from your own storage, so a Hub outage or throttling does not stop builds that use those images.

What a pull-through cache does

When a build asks the mirror for an image it does not have, the mirror fetches it from Docker Hub and keeps a copy. Later requests come from the copy. Docker's documentation describes running the official Registry image as the cache, with a proxy section in its configuration.

The point for resilience is simple: a cache only helps with images it has already seen. Warm it before you need it.

Setup steps

1. Run the registry image with a proxy block whose remoteurl is Docker Hub's registry address.
2. Use the filesystem storage driver, which Docker recommends for performance and correctness.
3. On every build host, add the mirror under registry-mirrors in the daemon's configuration file, then reload Docker.
4. Add authentication to the mirror. Docker warns that if you give the mirror Hub credentials, anything that user can reach becomes available through it.
5. Enable delete in the registry configuration so you can clean up the cache later.
6. Pull your base images once through the mirror to warm it.

Limits to know

• Only the central Docker Hub can be mirrored this way, not other private registries.
• Mirrors remain subject to Docker's fair use policy.
• If Hub access is blocked by an organization policy, pulls through the mirror also fail, with the documented workaround of pulling manually and retagging.
• Several caches sharing one backend do not guarantee that concurrent requests avoid duplicate pulls.
• A cache is not a vault. It is built for speed and availability, not as a managed record of what you shipped, so keep your own list of approved image versions.

Cache versus copying images into your own registry

Many teams use both: a cache for convenience, and a curated internal copy of the base images they approve.

Try it yourself

Click through it at your own pace, or open it full screen.

Look at how an image breaks down into layers and packages. Whatever your cache serves still needs scanning, because a copy of a vulnerable base image is still vulnerable.

Safeguard scans container images for vulnerabilities and can gate builds on the result. Try a free scan.

Quick check

Sources

• Docker docs: Registry as a pull-through cache

Last reviewed: 19 October 2026.