Using Container Registry's Docker Hub mirror

Container Registry mirrors public Docker Hub images that are frequently requested by Container Registry users. These images 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 the Docker Hub registry mirror. Changes in Docker Hub to mirrored images will be captured by the Container Registry mirror within 30 minutes or less.

You can configure your Docker daemon to fetch images from Container Registry's Docker Hub registry mirror. With Container Registry configured as a mirror, when you fetch a public image:

  • The Docker daemon checks the Container Registry registry and fetches the images if it exists. You can have multiple mirrors configured, for example you may also have your own local mirror. The Docker daemon will check each configured 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.
  • Container Registry will add frequently requested images to the mirror so they are available for future requests.

Container Registry's mirror is a cache, and mirrors images for which it receives requests. Container Registry will periodically remove images that are no longer requested.

Fetch images from Container Registry's mirror

To configure your Docker daemon to fetch images from Container Registry's mirror, follow the instructions below.


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

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

        "registry-mirrors": [""]
    • Or, when you start the daemon, pass in the Container Registry hostname:

      dockerd --registry-mirror=
    • Or, add the following line to your /etc/default/docker file:

      DOCKER_OPTS="${DOCKER_OPTS} --registry-mirror="
  2. Depending on your platform, run one of the following commands to restart the Docker daemon:

    sudo service docker restart
    sudo service docker stop && sudo service docker start
    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 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:

Now, any docker pull commands used to pull Docker Hub images will first be requested from Container Registry's mirror.

View the 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

    This command prints the list of repositories that are directly under Some of these repositories are nested, for example 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, for example

    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

    where REPOSITORY is one of the repositories nested under

What's next