Rename A Docker Image

The short answer

In Docker, renaming an image essentially consists in creating a copy of that image under a new name using the [.inline-code]docker tag[.inline-code] command as follows:

$ docker tag <source_name> <target_name>

Where:

• [.inline-code]source_name[.inline-code] is the current name of the image.
• [.inline-code]target_name[.inline-code] is the new name of the image.

For example, the following command will create a copy of the [.inline-code]api[.inline-code] image named [.inline-code]node-api[.inline-code]:

 $ docker tag api node-api

Note that since the [.inline-code]docker tag[.inline-code] command creates a copy of the source image, it will have to be manually removed using the [.inline-code]docker rmi[.inline-code] command.

[#easily-recall-with-ai] Easily retrieve these commands using Warp's AI Command Suggestion feature [#easily-recall-with-ai]

If you’re using Warp as your terminal, you can easily retrieve this command using the Warp AI Command Suggestions feature:

Entering [.inline-code]docker rename image[.inline-code] in the AI Command Search will prompt a [.inline-code]docker[.inline-code] command that can then quickly be inserted into your shell by doing CMD+ENTER.

[#clean-up-old-images] Cleaning up old images [#clean-up-old-images]

Since the [.inline-code]docker tag[.inline-code] command creates copies of existing images, it is common practice to periodically clean up some of these images to reclaim disk space, keep a clutter-free Docker environment, and prevent the risk of inadvertently using outdated image layers when building other images.

You can learn more about removing Docker images by reading our other article on how to remove a Docker image locally and on a Docker registry.

[#rename-images-with-new-tags] Renaming a Docker image with a new tag [#rename-images-with-new-tags]

In Docker, a tag is an optional human-readable identifier that specifies the version number or name of a Docker image, allowing users to differentiate between the different releases, builds, or variations of that image.

To rename a Docker image with a new tag, you can use the [.inline-code]docker tag[.inline-code] command with the following syntax:

 $ docker tag <source_name>[:<tag>] <target_name>[:<tag>]

Where:

• [.inline-code]tag[.inline-code] is a string of characters. Note that if [.inline-code]tag[.inline-code] is unspecified it defaults to [.inline-code]latest[.inline-code].

For example, the following command will create a copy of the [.inline-code]api[.inline-code] image with the [.inline-code]latest[.inline-code] tag named [.inline-code]node-api[.inline-code] with the [.inline-code]beta[.inline-code] tag:

 $ docker tag api:latest node-api:beta

Note that since the [.inline-code]latest[.inline-code] tag is implied when not specified, the above command can also be written as follows:

 $ docker tag api node-api:beta

[#rename-images-using-ids] Renaming a Docker image using its ID [#rename-images-using-ids]

In Docker, images can also be renamed using their ID instead of their name, using the following syntax:

 $ docker tag <source_ID> <target_name>[:<tag]

Where:

• [.inline-code]source_ID[.inline-code] is the ID of the image obtained using the [.inline-code]docker images[.inline-code] command.

This syntax is particularly useful for images tagged as [.inline-code]<none>[.inline-code], which may refer to intermediate images created during the build process of a Dockerfile, incomplete or failed image pulls, improperly untagged images, or orphaned images.

For example, the following command will rename the image identified by the [.inline-code]cd4b71a66dc1[.inline-code] ID to [.inline-code]node-api:latest[.inline-code]:

$ docker tag cd4b71a66dc1 node-api

[#rename-images-on-the-docker-registry] Renaming a Docker image on a registry [#rename-images-on-the-docker-registry]

To rename a Docker image hosted on the public Docker registry, you can use the [.inline-code]docker tag[.inline-code] command with the following syntax:

 $ docker tag <source>[:<tag>] [<namespace>:]<target_name>[:<tag>]

Where:

• [.inline-code]source[.inline-code] is either the name or ID of the image.

• [.inline-code]namespace[.inline-code] is an optional string describing a username or an organization's name. It defaults to [.inline-code]library[.inline-code] if not specified.

The newly tagged image can then be uploaded to the registry using the [.inline-code]docker push[.inline-code] command as follows:

 $ docker push [<namespace>:]<target_name>[:<tag>]

For example, the following command will take the image named [.inline-code]api[.inline-code] with the [.inline-code]dev[.inline-code] tag and create a new image with the same name and the [.inline-code]beta[.inline-code] tag within the [.inline-code]webapis[.inline-code] namespace:

 $ docker tag api:dev webapis/api:beta

And the following command will upload this newly tagged image to the public Docker registry:

 $ docker push webapis/api:beta

[#rename-images-on-a-private-registry] Renaming a Docker image on a private registry [#rename-images-on-a-private-registry]

To rename a Docker image hosted on a private registry, you can use the [.inline-code]docker tag[.inline-code] command with the following syntax instead:

$ docker tag <source>[:<tag>] <host>[:<port>][/<namespace>]/<target_name>[:<tag>]

Where:

• [.inline-code]host[.inline-code] is the hostname of the privately hosted registry.
• [.inline-code]port[.inline-code] is the optional network port of the registry.

For example, the following command will take the image named [.inline-code]api[.inline-code] with the [.inline-code]dev[.inline-code] tag and create a new image with the same name and the [.inline-code]beta[.inline-code] tag within the [.inline-code]webapis[.inline-code] namespace hosted at [.inline-code]registry.example.com:8000[.inline-code]:

$ docker tag api:dev registry.example.com:8000/webapis/api:beta

And the following command will upload this newly tagged image to the specified registry:

$ docker push registry.example.com:8000/webapis/api:beta