Pushing and pulling images

This page describes how to push and pull container images.

For instructions on listing, tagging, and deleting images, see Managing images.

Before you begin

If the target repository does not exist, create a new repository.
You must have at least Artifact Registry Writer access to the repository.
Install Docker if it is not already installed.
Configure authentication for Docker.

Pushing an image

To push a local image to a Artifact Registry repository, you tag it with the repository name and then push the image.

If you are uploading large images, the following limits apply:

Upload time: If you authenticate to Artifact 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: The maximum artifact size is 5 TB.; Artifact 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 Artifact Registry.

Tagging the local image

Determine the name of the image. The format of a full image name is:
```
LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
```
where:
- LOCATION is the regional or multi-regional location of the repository where the image is stored.
- PROJECT is your Google Cloud Console project ID. If your project ID contains a colon (:), see Domain-scoped projects.
- REPOSITORY is the name of the repository where the image is stored.
- IMAGE is the image's name. It can be different than the image's local name.
For example, consider an image with the following characteristics:
- Repository location: us
- Repository name: my-repo
- Project ID: my-project
- Local image name: my-image
- Target image name: test-image
This image name for this example is:
```
us-docker.pkg.dev/my-project/my-repo/test-image
```
Note: The name for the image that you will store in the repository can be different from the image name on your local machine.

For details about the image name format, including handling domain-scoped projects, see Repository and image names.
Tag the local image with the repository name with the command:
```
docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
```
where SOURCE-IMAGE is the local image name or image ID.

This command names the image with the repository name and applies the tag latest.

For the example image from the previous step, you would use the following command if the local image my-image is in the current directory:
```
docker tag my-image us-docker.pkg.dev/my-project/my-repo/test-image
```
If you want to apply a specific tag, use the command:
```
docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
```
To use the tag staging with the example image, you add :staging to the command:
```
docker tag my-image us-docker.pkg.dev/my-project/my-repo/test-image:staging
```

Push the tagged image to Artifact Registry

Push the tagged image with the command:

docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/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 LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

When you push an image, it is stored in the specified repository.

After pushing your image, you can:

Go to the Cloud Console to view the image.

Run the gcloud command to view the image's tags and automatically-generated digest:

gcloud artifacts docker images list \
LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]

The following example output shows truncated image digests, but the command always returns the full image digest.

 IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46
  ```

Pulling images

To pull from a repository, use the command:

docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

where:

LOCATION is the regional or multi-regional location of the repository where the image is stored.
PROJECT is your Google Cloud Console project ID. If your project ID contains a colon (:), see Domain-scoped projects.
REPOSITORY is the name of the repository where the image is stored.
IMAGE is the image's name in the repository.
TAG is the tag for the image version that you want to pull.
IMAGE-DIGEST is the sha256 hash value of the image contents. Each version of an image has a unique image digest. In Google Cloud Console, click on the specific image to see its metadata. The digest is listed as the Image digest.

For example, consider an image with the following characteristics:

Repository location: us
Repository name: my-repo
Project ID: my-project
Image name: test-image
Tag: staging

This command to pull the image is:

docker pull us-docker.pkg.dev/my-project/my-repo/test-image:staging

What's next

Learn about managing tags and deleting images.
If you want to run containers on Compute Engine, learn about containers on Compute Engine.