Mirroring the Docker Hub Library for Local Image Caching

--- description: Setting-up a local mirror for Docker Hub images keywords: registry, on-prem, images, tags, repository, distribution, mirror, Hub, recipe, advanced title: Mirror the Docker Hub library linkTitle: Mirror weight: 80 aliases: - /engine/admin/registry_mirror/ - /registry/recipes/mirror/ - /docker-hub/mirror/ --- ## Use-case If you have multiple instances of Docker running in your environment, such as multiple physical or virtual machines all running Docker, each daemon goes out to the internet and fetches an image it doesn't have locally, from the Docker repository. You can run a local registry mirror and point all your daemons there, to avoid this extra internet traffic. > [!NOTE] > > Docker Official Images are an intellectual property of Docker. ### Alternatives Alternatively, if the set of images you are using is well delimited, you can simply pull them manually and push them to a simple, local, private registry. Furthermore, if your images are all built in-house, not using the Hub at all and relying entirely on your local registry is the simplest scenario. ### Gotcha It's currently not possible to mirror another private registry. Only the central Hub can be mirrored. > [!NOTE] > > Mirrors of Docker Hub are still subject to Docker's [fair use policy](/manuals/docker-hub/usage/_index.md#fair-use). ### Solution The Registry can be configured as a pull through cache. In this mode a Registry responds to all normal docker pull requests but stores all content locally. ### Using Registry Access Management (RAM) with a registry mirror If Docker Hub access is restricted via your Registry Access Management (RAM) configuration, you will not be able to pull images originating from Docker Hub even if the images are available in your registry mirror. You will encounter the following error: ```console Error response from daemon: Access to docker.io has been restricted by your administrators. ``` If you are unable to allow access to Docker Hub, you can manually pull from your registry mirror and optionally, retag the image. For example: ```console docker pull <your-registry-mirror>[:<port>]/library/busybox docker tag <your-registry-mirror>[:<port>]/library/busybox:latest busybox:latest ``` ## How does it work? The first time you request an image from your local registry mirror, it pulls the image from the public Docker registry and stores it locally before handing it back to you. On subsequent requests, the local registry mirror is able to serve the image from its own storage. ### What if the content changes on the Hub? When a pull is attempted with a tag, the Registry checks the remote to ensure if it has the latest version of the requested content. Otherwise, it

This document explains how to set up a local Docker registry mirror to cache images from Docker Hub, reducing internet traffic for multiple Docker instances. It outlines alternative solutions like using a private registry for a defined set of images or relying solely on a local registry for in-house builds. The registry mirror acts as a pull-through cache, storing images locally after the first request. It also addresses using Registry Access Management (RAM) and notes that the registry checks the remote to ensure it has the latest version of the requested content.