Pushing and Pulling Images

Pushing and pulling Docker images is one of the most common tasks completed with Container Registry. Before pushing an image, you must choose a registry name, then tag the image appropriately.

This guide assumes that you have the Cloud SDK installed, which includes the gcloud command-line tool. See also the Container Registry quickstart, which explains how to get up and running with the product.

For instructions on listing, tagging, and deleting images, see Managing Images.

Choosing a registry name

Before you can push a Docker image to any private registry, you need to tag the image with a registry name.

Your private registry name is a string combining your Google Cloud Platform project ID with a gcr.io hostname, your image's name, and (optionally) its tag.

The following is the list of available gcr.io hostnames:

  • us.gcr.io hosts your images in the United States
  • eu.gcr.io hosts your images in the European Union
  • asia.gcr.io hosts your images in Asia
  • gcr.io without a prefix hosts your images in the United States, but this behavior may change in a future release

Registry name format

The registry name format is below:



  • [HOSTNAME] is the gcr.io hostname
  • [YOUR-PROJECT-ID] is your Google Cloud Platform Console project ID
  • [IMAGE] is your image's name
  • Optionally, [:TAG] is the image's tag (if omitted, default value is latest)

For example, example-image from my-project, served in the United States, has the following registry name with the tag test:


If your project ID looks like example.com:foo-bar, and you are using Docker 1.8 or later, use:


If you don't know your project ID, run the following command:

gcloud projects list

Domain-scoped projects

If your project is scoped to your domain, such as gcr.io/example.com/my-project/my-image, use:


Pushing images to the registry

To push to Container Registry, perform the steps below:

  1. Tag your image by running the following Docker command, in which [:TAG] is optional. If omitted, the latest tag is automatically used:

    docker tag [IMAGE] [HOSTNAME]/[PROJECT-ID]/[IMAGE][:TAG]
  2. Then, push the image to Container Registry:

    gcloud docker -- push [HOSTNAME]/[PROJECT-ID]/[IMAGE]

    Or, using a tag:

    gcloud docker -- push [HOSTNAME]/[PROJECT-ID]/[IMAGE][:TAG]

For example:

docker tag my-image gcr.io/my-project/my-image:test
gcloud docker -- push gcr.io/my-project/my-image

After pushing your image, you can run gcloud container images list-tags to view its tag and automatically-generated digest:

gcloud container images list-tags gcr.io/my-project/my-image

The command's output is similar to the following:

44bde...      test        2017-..-..

Pulling images from the registry

To pull from Container Registry, run the following command:

gcloud docker -- pull [HOSTNAME]/[PROJECT-ID]/[IMAGE]

For example:

gcloud docker -- pull gcr.io/my-project/my-image

To pull a specific tag or digest of an image, append the image's tag or digest:

gcloud docker -- pull gcr.io/my-project/my-image:test
gcloud docker -- pull gcr.io/my-project/my-image@sha256:44bde...

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Container Registry