When working with Docker images, it’s common to want to rename an image—whether to change its repository name, tag, or organize it under a different namespace. Thankfully, Docker makes it easy to do this using the docker tag command.
In this blog post, you’ll learn:
- How Docker image naming works
- How to rename a Docker image (or repository name)
- Best practices for image management
🧠 Understanding Docker Image Naming
A typical Docker image name follows this pattern:
[registry/][user/]repository[:tag]
Examples:
ubuntu:latestmyuser/myapp:1.0registry.example.com/team/image:v2
Each name consists of:
- Registry (optional) – like Docker Hub or a private registry
- Username/organization – optional on Docker Hub
- Repository name – the main identifier
- Tag – version or variant (defaults to
latestif omitted)
🛠️ How to Rename a Docker Image
Docker does not have a direct rename command, but you can retag the image with a new name, then optionally remove the old one.
✅ Step 1: Tag the Image with a New Name
docker tag old-image-name new-repo-name[:new-tag]
Example:
docker tag myapp:1.0 myusername/myapp-renamed:2.0
This creates a new tag (new name) pointing to the same image ID.
✅ Step 2: Verify the New Image Name
docker images
You should see both the original and new image names in the list, sharing the same IMAGE ID.
✅ Step 3 (Optional): Remove the Old Image Name
If you no longer want the original name:
docker rmi old-image-name[:tag]
Example:
docker rmi myapp:1.0
⚠️ This removes the tag, not the image itself—the image remains as long as it’s tagged elsewhere.
🔁 Summary Workflow
# Rename or retag the image
docker tag oldname:tag newname:tag
# (Optional) Remove the old name
docker rmi oldname:tag
💡 Tips for Image Naming
- Use semantic versioning in tags (e.g.,
v1.0.0) - Include your Docker Hub or registry username
- Use lowercase letters and avoid special characters
- Keep repository names descriptive but concise
📝 Conclusion
While Docker doesn’t support direct image renaming, the docker tag command provides a simple and effective way to change repository names or rename images. By retagging and optionally removing old references, you can maintain a clean and organized local image library.
🔑 Quick Recap
| Task | Command |
|---|---|
| Rename/Retag image | docker tag old new |
| Verify new tag | docker images |
| Remove old name | docker rmi old |