Run a registry as a pull-through cache and point your Docker daemons at it with the registry-mirrors setting. Every pull goes to your mirror first, which stores what it fetches from Docker Hub. This cuts external traffic and gives you one place to control and inspect images.
Why run a mirror at all?
Docker's documentation describes the use case: if many machines run Docker, each daemon goes out to the internet to fetch images it does not have. A local mirror removes that repeated traffic. It also removes a dependency on Hub being reachable from every build host, and it gives you a choke point where you can log and later scan what your builds pulled.
Docker also notes that mirrors of Docker Hub are still subject to Docker's fair use policy, and that Docker Official Images are Docker's intellectual property. A mirror is not a way around the terms.
How does it work?
The Docker Registry can be configured as a pull-through cache. In that mode it answers normal docker pull requests but stores all content locally. The first pull of an image fetches it from Hub. Later pulls come from disk.
On each machine you tell the daemon about it, either with the mirror option when starting the daemon or by adding the registry-mirrors key to the daemon.json file, then reloading Docker. The value is the URL of your mirror host.
What are the limits?
Docker states a limitation directly: it is currently not possible to mirror another private registry. Only the central Hub can be mirrored this way. If you also pull from other registries, you need a different approach, such as pushing approved copies into your own registry and referencing those names.
There is also a trust question. A mirror stores whatever it fetched, so a bad image fetched once is served to everyone until it ages out. The mirror speeds up delivery. It does not decide what is safe.
A constructed example
A team of forty engineers and a small build farm all pull node and postgres. Before a mirror, a Hub slowdown stalls every pipeline at once. After deploying a cache on an internal host, builds keep working through an outage for any image already pulled. The team also gets a pull log showing which tags were requested, which later helps them notice an unexpected image name.
How to check or apply this
- Deploy the registry in pull-through mode on an internal host, with disk sized for your image set.
- Put it behind TLS and restrict network access to your build hosts and developers.
- Add the mirror URL to the registry-mirrors key in each daemon's configuration and reload.
- Pull a known image and confirm it appears in the mirror's storage.
- Pin base images by digest in Dockerfiles, so a cached tag change cannot change a build silently.
- Scan images that pass through the mirror, and log pulls for review.
- Plan for images from other registries separately, since the mirror covers Hub only.
If you restrict Hub access with Registry Access Management, read Docker's note on how that interacts with a mirror before rolling out.
Safeguard can scan dependencies for known vulnerabilities, which pairs well with a mirror that gives you a single pull point.
Quick check
Can a Docker Hub mirror also cache images from my private registry?
Not through this feature. Docker documents that only the central Hub can be mirrored, not another private registry.
Does a mirror make images safer?
No. It stores what it fetched. Add digest pinning and scanning to decide what is acceptable.
Sources
Last reviewed: 18 October 2026.
