Docker: How to Change Repository Name or Rename an Image

When working with Docker, it’s common to build and tag images locally. But sometimes, you may need to rename a Docker image — either to change the repository name, retag for a different registry, or clean up your image list.

In this article, we’ll explore how to rename a Docker image or change its repository name using safe and simple commands.

Table of Contents

🎯 Use Case Examples

You might want to rename or retag a Docker image when:

Moving an image from a local tag to a Docker Hub or private registry
Correcting a misspelled repository name
Preparing for a CI/CD pipeline
Switching between environments (dev, staging, prod)

🔄 Docker Doesn’t Rename — It Retags

Docker doesn’t literally rename images. Instead, it allows you to re-tag an existing image with a new name, then optionally delete the old tag.

🛠️ Syntax: `docker tag`

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

This creates a new tag pointing to the same image ID — no duplication of image layers.

✅ Example 1: Change Local Repository Name

docker images

Suppose you have an image like:

REPOSITORY      TAG       IMAGE ID       CREATED         SIZE
old-name        latest    123abc456def   5 minutes ago   200MB

Rename to `new-name`:

docker tag old-name new-name

Now both names will point to the same image:

REPOSITORY      TAG       IMAGE ID       CREATED         SIZE
old-name        latest    123abc456def   5 minutes ago   200MB
new-name        latest    123abc456def   5 minutes ago   200MB

You can remove the old one if needed:

docker rmi old-name

✅ Example 2: Retag for Docker Hub or Registry

Let’s say you want to push the image to Docker Hub:

docker tag my-image username/my-image
docker push username/my-image

Or for a private registry:

docker tag my-image registry.example.com/my-repo/my-image
docker push registry.example.com/my-repo/my-image

✅ Example 3: Retag with a New Version

docker tag my-image:latest my-image:v2.0

Now your image list will show:

my-image       latest    123abc456def
my-image       v2.0      123abc456def

This is especially useful for versioning images in CI/CD pipelines.

📦 Cleaning Up Old Tags

Remember, tags are references, not separate images. You can remove a tag safely:

docker rmi old-tag

This won’t delete the underlying image unless no other tag points to it.

🔐 Final Notes

Renaming via docker tag is non-destructive and quick
Works with both local and pulled images
Helps organize and prepare images for registry pushes
Supports multi-tagging for versioning and environments

🧭 Summary

Task	Command
Rename/repository retag	`docker tag old-name new-name`
Add version tag	`docker tag image:latest image:v2.0`
Push to Docker Hub	`docker tag image username/image && docker push username/image`
Remove old tag	`docker rmi old-name`

Renaming Docker images is really just retagging — a flexible, powerful feature to keep your image workflows organized.