Artifact Registry is a universal package management service that supports containers and other formats. Learn about transitioning from Container Registry to gain greater flexibility and control over your artifacts.

Pushing and pulling images

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 have:

  1. Enabled Container Registry in your project.

  2. Installed and configured Docker.

  3. Verified that you have permissions to push and pull images.

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.

The very first image that you push to a multi-regional host will create the storage bucket for that hostname in your Google Cloud project.

The following factors might impact uploads for large images:

Upload time
Any request sent to Container Registry has a 2 hour timeout limit. If you authenticate to Container Registry using an access token, the token expires after 60 minutes. If you expect your upload time to exceed 60 minutes, use a different authentication method.
Image size
Container Registry uses Cloud Storage for each registry's underlying storage. Cloud Storage quotas and limits apply to each registry, including the 5 TB maximum size for an object in storage.
Container Registry does not support Docker chunked uploads. Some tools support uploading large images with either chunked uploads or a single monolithic upload. You must use monolithic uploads to push images to Container Registry.

Tag the local image with the registry name

  1. Determine the registry name:

    1. Choose a hostname, which specifies location where you will store the image.

      • gcr.io hosts images in data centers in the United States, but the location may change in the future
      • us.gcr.io hosts image in data centers in the United States, in a separate storage bucket from images hosted by gcr.io
      • eu.gcr.io hosts the images in the European Union
      • asia.gcr.io hosts 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.

    2. Choose an image name, which can be different from the image's name on your local machine.

    3. Combine the hostname, your Google Cloud Console project ID, and image name:

      HOSTNAME/PROJECT-ID/IMAGE

      If your project ID contains a colon (:), see Domain-scoped projects.

  2. Tag the local image with the registry name by using the command:

    docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/IMAGE

    where 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 use the 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.

  • Run gcloud container images list-tags to 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

or

docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST

where:

  • HOSTNAME is listed under Location in the console. It's one of four options: gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
  • HOSTNAME 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 Cloud 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:

  1. Click on the name of an image to go to the specific registry.

  2. In the registry, check the box next to the version of the image that you want to pull.

  3. Click SHOW PULL COMMAND on the top of the page.

  4. Copy the pull command, which identifies the image using either the tag or the digest.

What's next