Pulling cached Docker Hub images

Container Registry caches frequently-accessed public Docker Hub images on mirror.gcr.io. You can configure the Docker daemon to use a cached public image if it is available from the mirror, or pull the image from Docker Hub if a cached copy is unavailable.

Cached images in the Container Registry mirror are:

  • Stored in a repository that Google owns.
  • More insulated from Docker Hub outages.
  • Easily integrated with the Google Cloud ecosystem.
  • Kept in sync with Docker Hub. Changes in Docker Hub will be captured by the Container Registry mirror within 30 minutes or less.

Configuring the Docker daemon

To configure your Docker daemon to pull images from the Container Registry mirror:


  1. Configure the daemon in one of the following ways:

    • To configure the Docker daemon automatically on startup, set the following value in /etc/docker/daemon.json

        "registry-mirrors": ["https://mirror.gcr.io"]
    • When you start the daemon, pass in the Container Registry hostname:

      dockerd --registry-mirror=https://mirror.gcr.io
    • Add the following line to your /etc/default/docker file:

      DOCKER_OPTS="${DOCKER_OPTS} --registry-mirror=https://mirror.gcr.io"
  2. Restart the Docker daemon.

    • On Linux, run one of the following commands:

      sudo service docker restart


      sudo service docker stop && sudo service docker start
    • On macOS or Windows, run the following command:

      docker-machine restart

Docker UI

  1. Open Docker's Preferences menu.
  2. Click Daemon.
  3. Click Advanced. In the JSON field, add a registry-mirrors key with https://mirror.gcr.io as a value:

      "registry-mirrors" : [
  4. Click Apply & Restart.

To make sure the mirror is now configured, run:

docker system info

The output should include Registry Mirrors, and should look similar to the following:

Containers: 2
 Running: 0
 Paused: 0
 Stopped: 2
Images: 2
Server Version: 17.03.1-ce
Storage Driver: overlay2
 Backing Filesystem: extfs
 Supports d_type: true
 Native Overlay Diff: true
Logging Driver: json-file
Registry Mirrors:

Pulling cached images

Container Registry adds frequently requested images to the mirror so they are available for future requests. It also periodically removes images that are no longer requested.

There is no guarantee that a particular image will remain cached for an extended period of time, so only use the mirror by configuring the Docker daemon to check for cached images instead of pulling images directly from mirror.gcr.io.

After you configure the Docker daemon to use the Container Registry mirror, Docker performs the following steps when you pull a public Docker Hub image with a docker pull command:

  • The Docker daemon checks the Container Registry mirror and fetches the images if it exists. If you have multiple mirrors configured, the Docker daemon checks each mirror for the image until it is found.
  • If the image isn't found, the Docker daemon fetches the image from the canonical repository on Docker Hub.

Viewing a list of mirrored images

You can view the list of repositories and the list of tags and digests in a specific repository.

  • To view the list of repositories that are in the Container Registry's mirror, run the command:

    gcloud container images list --repository=mirror.gcr.io

    This command prints the list of repositories that are directly under mirror.gcr.io. Some of these repositories are nested, for example mirror.gcr.io/library has more repositories nested underneath it.

    You can view the list of the nested repositories using:

    gcloud container images list --repository=REPOSITORY

    where REPOSITORY is a repository under mirror.gcr.io, for example mirror.gcr.io/library.

    This command prints the list of repositories that are directly under the repository you specified.

  • To view the tags and digests in one of these repositories, use the command:

    gcloud container images list-tags mirror.gcr.io/REPOSITORY

    where REPOSITORY is one of the repositories nested under mirror.gcr.io.

What's next