HOWTO · Docker

How to Rename a Docker Image with a New Tag

Retag an existing Docker image from the command line, verify the new reference, and understand when removing the old tag can remove the local image.

On this page

Docker does not rename an image in place. To give an existing image another repository name or tag without rebuilding it, add a second reference with docker image tag (also available as docker tag). The source and target references then point to the same image ID. You can remove the old reference after verifying the new one.

Understand Docker image names and tags

An image reference usually has the form [HOST[:PORT]/]NAMESPACE/REPOSITORY[:TAG]. The registry host and namespace are optional; if you omit a tag, Docker uses latest. A tag is a readable reference to an image, not a new copy of its layers. Retagging changes which names you can use to refer to the image; it does not rename a container or rebuild the image.

For example, local-api:latest and registry.example/team/api:1.0 can be two references to one local image. Replace these sample references with names that fit your repository and registry. Adding a registry name locally does not upload the image; use docker image push separately when you need to publish it.

Add a new tag to an image

Use the existing image name as the source and the desired reference as the target:

source='local-api:latest'
target='registry.example/team/api:1.0'
printf 'docker image tag %s %s\n' "$source" "$target"

Run this example to print the command with the sample references. To retag your image, run docker image tag local-api:latest registry.example/team/api:1.0 in a shell where Docker can access that image. The command normally produces no success text; a nonzero exit status indicates that Docker could not apply the tag. The printed example above is only a command template and does not contact a Docker daemon.

You can also use an image ID as the source: docker image tag IMAGE_ID registry.example/team/api:1.0. Find IDs with docker image ls --no-trunc. If you use a shortened ID, ensure that it uniquely identifies the intended image; do not assume a fixed number of characters is sufficient. Using the full ID avoids ambiguity.

Verify the new tag and remove the old tag

List matching references with docker image ls. To compare their image IDs, inspect each reference with docker image inspect --format '{{.Id}}' local-api:latest and docker image inspect --format '{{.Id}}' registry.example/team/api:1.0. Matching IDs confirm that both names identify the same local image. These commands depend on the images being present in the Docker daemon you are querying.

After confirming the new reference, remove the old name with docker image rm local-api:latest. This removes that reference. If it was the image’s last reference, Docker may remove the image from local storage as well. Keep another tag if you want a named reference to remain, and check which image you are removing before running the command.

Common questions and limitations

Does retagging rebuild or upload the image? No. Adding a tag creates a local reference; it does not rebuild image contents or push them to a registry. Build and push are separate operations.

Is an image the same as a container? No. An image is a template used to create containers. Retagging an image does not rename containers created from it. Container names are managed separately with docker rename.

Why can Docker not find the source? Check the spelling and tag, and confirm the image exists in the daemon selected by your Docker context. A short image ID must uniquely identify the intended image. If the target name includes a registry, remember that tagging alone does not publish it.