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, and have set up a Docker
credential helper for Container Registry. 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:
[HOSTNAME]is the gcr.io hostname
[PROJECT-ID]is your Google Cloud Platform Console project ID
[IMAGE]is your image's name
[:TAG|@DIGEST]is the image's tag or digest (if omitted, the default value is
my-project, served in the United States,
has the following registry name with the tag
If you don't know your project ID, run the following command:
gcloud projects list
If your project is scoped to your domain, such as
Pushing images to the registry
To push a local image to Container Registry, perform the steps below:
Tag your image by running the following Docker command:
docker tag [SOURCE_IMAGE] [HOSTNAME]/[PROJECT-ID]/[IMAGE][:TAG]
[SOURCE_IMAGE]is the image you are pushing to the registry, which must exist locally on the same machine where you're executing the docker command.
[HOSTNAME]is one of the gcr.io hostnames.
[PROJECT-ID]is the ID of your project.
[IMAGE]is the desired image name. This name can be different from the source name.
[:TAG]is optional. If omitted, the tag
latestis automatically applied.
Configure Docker to use
gcloudas a Container Registry credential helper (you are only required to do this once):
gcloud auth configure-docker
Then, push the image to Container Registry:
docker push [HOSTNAME]/[PROJECT-ID]/[IMAGE]
Or, using a tag:
docker push [HOSTNAME]/[PROJECT-ID]/[IMAGE][:TAG]
docker tag my-image gcr.io/my-project/my-image:test 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:
DIGEST TAGS TIMESTAMP 44bde... test 2017-..-..
Pulling images from the registry
To pull from Container Registry, configure Docker to use
gcloud as a
credential helper (you are only required to do this once):
gcloud auth configure-docker
Then, run the following command:
docker pull [HOSTNAME]/[PROJECT-ID]/[IMAGE]
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:
docker pull gcr.io/my-project/my-image:test docker pull gcr.io/my-project/my-image@sha256:44bde...