Managing images

This page explains how to manage container images in a Docker repository. Managing images includes listing images in a repository, adding tags, deleting tags, copying images to a new repository, and deleting images.

For information about pushing and pulling images, see Pushing and pulling images.

Before you begin

  1. If the target repository does not exist, create a new repository.
  2. Verify that you have the required permissions for the repository.
  3. (Optional) Configure defaults for gcloud commands.

Listing images

You can list the images using the Google Cloud Console or the command line.

The repository list includes both Artifact Registry and Container Registry repositories. To work with images in a Container Registry repository, see the Container Registry documentation for managing images.

Console

To view a list of images or image versions:

  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. Click the repository that contains the image.

  3. Click on an image to see versions of the image, including digests and tags.

gcloud

To list all images in the default project, repository, and location when the default values are configured:

gcloud artifacts docker images list [--include-tags]
 

To list all images in a repository in a specific location, run the command:

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

To list all digests and tags for a specific image, run the command:

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

Where

  • LOCATION is the regional or multi-regional location of the repository.
  • 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 name of the image in the repository.
  • --include-tags shows all versions of images, including digests and tags. If this flag is omitted, the returned list only includes top level container images.

For example, consider an image with the following characteristics:

  • Repository location: us
  • Repository name: my-repo
  • Project ID: my-project
  • Image name: my-image

This full repository name is:

us-docker.pkg.dev/my-project/my-repo

This full image name is:

us-docker.pkg.dev/my-project/my-repo/my-image

For details about the image name format, including handling domain-scoped projects, see Repository and image names.

Tagging images

You can tag existing images in a Artifact Registry repository or you can tag them before you push them to a repository.

Tagging images in a repository

You can add a tag to an image in a Artifact Registry repository using the Google Cloud Console or the command line. In a repository, tags are unique to a version of an image. So if you have multiple versions of an image, each tag only applies to one of the versions. If you tag an image with a tag that's already in use, you will move the tag from the original version to the newly tagged version.

Console

To tag an existing image in a repository:

  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. Click the image to view versions of the image.

  3. Select the image version to tag.

  4. In the row of the selected version, click More actions (More actions), and then click Edit tags.

  5. Type new tags into the field and then click SAVE.

gcloud

To tag existing images in a repository, specify the image version using the image digest or tag, and then specify the tag to add. Run one of the following commands:

gcloud artifacts docker tags add IMAGE-VERSION TAG

Where

  • IMAGE-VERSION is the full name of the image version to tag, using either the image digest or an existing tag on the image version.
  • TAG is the full name of the tag that you want to add.

For example, consider an image with the following characteristics:

  • Repository location: us
  • Repository name: my-repo
  • Project ID: my-project
  • Image name: my-image
  • Existing tag: iteration6-final
  • Tag to add: release-candidate

To add the tag release-candidate to the version of the image with the tag iteration6-final, run the following command:

gcloud artifacts docker tags add \
us-docker.pkg.dev/my-project/my-repo/my-image:iteration6-final \
us-docker.pkg.dev/my-project/my-repo/my-image:release-candidate

For details about the image name format, including handling domain-scoped projects, see Repository and image names.

Tagging local images

To push any local image to Artifact Registry, you need to first tag it with the repository name and then push the image. For instructions, see Pushing and pulling.

Untagging images

You can remove a tag from an image in Artifact Registry using the Google Cloud Console or the command line.

Console

  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. Click the image to view versions of the image.

  3. Select the image version to untag.

  4. In the row of the selected version, click More actions (More actions), and then click Edit tags.

  5. Delete the tag and then click SAVE.

gcloud

To delete a tag and remove it from the image, run the following command:

 gcloud artifacts docker tags delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG
 

Where

  • LOCATION is the regional or multi-regional location of the repository.
  • 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 name of the image in the repository.
  • TAG is the tag for the version you want to delete.

Deleting images

You can delete an entire container image or delete a specific image version associated with a tag or digest. Once you have deleted an image, you cannot undo the action.

Other tools are available to help you manage unused images. For example the gcr-cleaner tool finds and deletes old images based on different criteria. Removing unused images can help you to reduce storage costs. The gcr-cleaner tool is not an official Google product.

To delete an images from Google Cloud Console or the gcloud tool:

Console

  1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

  2. Click on the image name to see versions of that image.

  3. Select versions that you want to delete.

  4. Click DELETE.

  5. In the confirmation dialog box, click DELETE.

gcloud

To delete an image and all its tags, run the command:

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE --delete-tags

To delete a specific image version, use one of the following commands.

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG [--delete-tags]
or
gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE@DIGEST [--delete-tags]

Where

  • LOCATION is the regional or multi-regional location of the repository.
  • 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 name of the image in the repository.
  • TAG is the tag for the version you want to delete. If multiple tags are associated with the same image version, you must include --delete-tags to delete the image version without removing the tags first.
  • IMAGE-DIGEST is the sha256 hash value for the version you want to delete. If a tag is associated with the image digest, you must include --delete-tags to delete the image version without removing the tag first.
  • --delete-tags removes all tags applied to the image version. This flag enables you to force deletion of an image version when:
    • You specified a tag, but there are other tags associated with the image version.
    • You specified an image digest that has at least one tag.