Amazon ECR
User Guide (API Version 2015-09-21)

Retagging an Image with the AWS CLI

With Docker Image Manifest V2 Schema 2 images, you can use the --image-tag option of the put-image command to retag an existing image, without pulling or pushing the image with Docker. For larger images, this process saves a considerable amount of network bandwidth and time required to retag an image.


This procedure works for Mac and Linux platforms. To use this procedure for Windows platforms, you must reconfigure the environment variable declaration and resolution in the commands below so that they work with your shell.

To retag an image with the AWS CLI

  1. Use the batch-get-image command to get the image manifest for the image to retag and set that value to an environment variable. In this example, the manifest for an image with the tag, latest, in the repository, amazonlinux, is set to the environment variable, MY_MANIFEST.

    $ MY_MANIFEST=$(aws ecr batch-get-image --repository-name amazonlinux --image-ids imageTag=latest --query images[].imageManifest --output text)

  2. Use the --image-tag option of the put-image command to put the image manifest to Amazon ECR with a new tag. In this example, the image is tagged as 2016.09.


    If the --image-tag option is not available in your version of the AWS CLI, upgrade to the latest version. For more information, see Installing the AWS Command Line Interface in the AWS Command Line Interface User Guide.

    $ aws ecr put-image --repository-name amazonlinux --image-tag 2016.09 --image-manifest "$MY_MANIFEST"

  3. Verify that your new image tag is attached to your image. In the output below, the image has the tags latest and 2016.09.

    $ aws ecr describe-images --repository-name amazonlinux { "imageDetails": [ { "imageSizeInBytes": 91769563, "imageDigest": "sha256:f1d4ae3f7261a72e98c6ebefe9985cf10a0ea5bd762585a43e0700ed99863807", "imageTags": [ "2016.09", "latest" ], "registryId": "aws_account_id", "repositoryName": "amazonlinux", "imagePushedAt": 1482187783.0 } ] }