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 docker tag command as follows:

$ docker tag <source_name> <target_name>

Run in Warp

Where:

• source_name is the current name of the image.
• target_name is the new name of the image.

For example, the following command will create a copy of the api image named node-api:

 $ docker tag api node-api

Run in Warp

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

Easily retrieve these commands using Warp's AI Command Suggestion feature

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

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

Cleaning up old images

Since the docker tag 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.

Renaming a Docker image with a new tag

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 docker tag command with the following syntax:

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

Run in Warp

Where:

• tag is a string of characters. Note that if tag is unspecified it defaults to latest.

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

 $ docker tag api:latest node-api:beta

Run in Warp

Note that since the latest tag is implied when not specified, the above command can also be written as follows:

 $ docker tag api node-api:beta

Run in Warp

Renaming a Docker image using its ID

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]

Run in Warp

Where:

• source_ID is the ID of the image obtained using the docker images command.

This syntax is particularly useful for images tagged as <none>, 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 cd4b71a66dc1 ID to node-api:latest:

$ docker tag cd4b71a66dc1 node-api

Run in Warp

Renaming a Docker image on a registry

To rename a Docker image hosted on the public Docker registry, you can use the docker tag command with the following syntax:

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

Run in Warp

Where:

• source is either the name or ID of the image.
• namespace is an optional string describing a username or an organization's name. It defaults to library if not specified.

The newly tagged image can then be uploaded to the registry using the docker push command as follows:

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

Run in Warp

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

 $ docker tag api:dev webapis/api:beta

Run in Warp

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

 $ docker push webapis/api:beta

Run in Warp

Renaming a Docker image on a private registry

To rename a Docker image hosted on a private registry, you can use the docker tag command with the following syntax instead:

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

Run in Warp

Where:

• host is the hostname of the privately hosted registry.
• port is the optional network port of the registry.

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

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

Run in Warp

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

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

Run in Warp