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 your Google Cloud Platform project ID combined with a gcr.io hostname:

  • 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
  • [IMAGE_ID] is your image's ID (from docker images list)

For example, example-image from awesome-project, served in the United States, has the following registry name:


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

Pushing images to the registry

To push to Container Registry, follow the steps below:

  1. Tag your image by running the following Docker command:

  2. Then, push the image to Container Registry by running the following command:

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

For example:

    docker tag 238971b38e2 gcr.io/awesome-project/example-image
    gcloud docker -- push gcr.io/awesome-project/example-image

Pulling images from the registry

To pull from Container Registry, run the following command:

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

For example:

gcloud docker -- pull gcr.io/awesome-project/example-image

What's next

Send feedback about...

Container Registry