How to Push and Pull Docker Images from Google Container Registry

Docker logo

Google Container Registry is a private storage service for Docker images, used to run containerized apps. It’s used to host images for deployment on other GCP container services, like Cloud Run and Kubernetes Engine.

What Is Google Container Registry?

When working with Docker images, you’ll often be pushing and pulling them from a container registry, used for storage and quick centralized access. The most popular registry is the official Docker Hub, which is public, but many cloud providers offer private container registries. Google’s Container Registry is one of these, providing your own registry for your GCP account.

It’s pretty simple to use. With some configuration of Docker, you should be able to push and pull images using docker tag and docker push, then have those updates deployed as container updates to Kubernetes Engine.

Container Registry isn’t available for accounts that haven’t enabled billing. It’s very cheap though—containers are stored in a Cloud Storage bucket, and you just pay the standard $0.026 per GB per month for storage, as well as standard data charges for egress. Optionally, you can enable “Vulnerability Scanning,” which costs $0.26 per container update to scan for vulnerabilities in the underlying software used in the container.

Pushing Images to GCR

Before we get started, you’ll need to make sure you’ve installed the Google Cloud SDK, which will give you access to the gcloud CLI. You’ll also of course need Docker installed to work with container images in the first place.

You’ll need to enable the Container Registry API. Click “Enable.”

enable container registry

Because the repositories are private, you’ll need to configure Docker to work with gcloud authentication, which can be done automatically with the following command that will make a few changes to your Docker config to add the gcloud CLI as a credential helper:

gcloud auth configure-docker

You’ll need your project ID for the next step; this is visible from the “Select Project” dropdown in the GCP console. Copy the ID.

copy project id

Then, you can tag the image as normal using docker tag, only supplying a custom hostname for GCR. By default, stores images in a cloud storage bucket located in the U.S. You can also use and for those regions.


This tags the image as latest, the default for new deployments, but if you want to use another tag, you can append :tag to the image name.

Once it’s tagged, you can upload it to GCR with docker push:

docker push[PROJECT-ID]/[IMAGE]

Once uploaded, they’ll be visible in the Container Registry console, or by running gcloud container images list-tags, and you’ll be able to use them for your Cloud Run and Kubernetes deployments.

If you you want to manually pull the image down, you can do so with docker pull:

docker pull[PROJECT-ID]/[IMAGE]:[TAG]

You’ll, of course, need gcloud installed and configured as a credential helper on the machine doing the pulling, or you won’t be able to authenticate.