Pushing (uploading) and pulling (downloading) images are two of the most common Container Registry tasks.
For instructions on listing, tagging, and deleting images, see Managing Images.
Before you begin
Make sure that you:
Enabled Container Registry in your project.
Configured Docker to authenticate to the registry.
Have permissions to push and pull from the registry.
Pushing an image to a registry
To push any local image to Container Registry, you need to first tag it with the registry name and then push the image.
Tag the local image with the registry name
Determine the registry name:
Choose a hostname, which specifies location where you will store the image.
gcr.iohosts images in data centers in the United States, but the location may change in the future
us.gcr.iohosts image in data centers in the United States, in a separate storage bucket from images hosted by
eu.gcr.iohosts the images in the European Union
asia.gcr.iohosts images in data centers in Asia
These locations correspond to the multi-regions for Cloud Storage storage buckets. When you push an image to a registry with a new hostname, Container Registry creates a storage bucket in the specified multi-region. This bucket is the underlying storage for the registry. Within a project, all registries with the same hostname share one storage bucket.
In the console, the images' hostname will be listed under Location.
Choose an image name, which can be different from the image's name on your local machine.
Combine the hostname, your Google Cloud Console project ID, and image name:
If your project ID contains a colon (
:), see Domain-scoped projects.
Tag the local image with the registry name by using the command:
docker tag [SOURCE_IMAGE] [HOSTNAME]/[PROJECT-ID]/[IMAGE]
[SOURCE_IMAGE]is the local image name or image ID.
This command names the image with the registry name and applies the tag
latest. If you want to apply a different tag, then use the command:
docker tag [SOURCE_IMAGE] [HOSTNAME]/[PROJECT-ID]/[IMAGE]:[TAG]
Push the tagged image to Container Registry
The Docker credential helper is the simplest way to
configure Docker to authenticate directly with Container Registry. You then
docker command to tag, push, and pull images. Alternatively, you can
use the client libraries
to manage container images, or you can interact directly with the Docker API.
Push the tagged image to Container Registry by using the command:
docker push [HOSTNAME]/[PROJECT-ID]/[IMAGE]
This command pushes the image that has the tag
latest. If you want to
push an image that has a different tag, use the command:
docker push [HOSTNAME]/[PROJECT-ID]/[IMAGE]:[TAG]
When you push an image to a registry with a new hostname, Container Registry creates a storage bucket in the specified multi-regional location. After pushing your image, you can:
Go to the Cloud Console to view the registry and image.
gcloud container images list-tagsto view the image's tag(s) and automatically-generated digest:
gcloud container images list-tags [HOSTNAME]/[PROJECT-ID]/[IMAGE]
The command's output is similar to the following:
DIGEST TAGS TIMESTAMP 44bde... test 2017-..-..
Pulling images from a registry
To pull from Container Registry, use the command:
docker pull [HOSTNAME]/[PROJECT-ID]/[IMAGE]:[TAG]
docker pull [HOSTNAME]/[PROJECT-ID]/[IMAGE]@[IMAGE_DIGEST]
[HOSTNAME]is listed under Location in the console. It's one of four options:
[PROJECT-ID]is your Google Cloud Console project ID. If your project ID contains a colon (
:), see Domain-scoped projects.
[IMAGE]is the image's name in Container Registry.
[TAG]is the tag applied to the image. In a registry, tags are unique to an image.
[IMAGE_DIGEST]is the sha256 hash value of the image contents. In the console, click on the specific image to see its metadata. The digest is listed as the Image digest.
To get the pull command for a specific image:
Click on the name of an image to go to the specific registry.
In the registry, check the box next to the version of the image that you want to pull.
Click SHOW PULL COMMAND on the top of the page.
Copy the pull command, which identifies the image using either the tag or the digest.
- Learn about managing your images, including adding or removing tags and deleting images.
- Learn about configuring access control.
- Read more about Container Registry's components and features.
- If you want to run containers on Compute Engine, learn about containers on Compute Engine.