docker rename image - How to Rename a Docker Image or Change Its Repository Name (docker tag + docker rmi, with Real Output)

TL;DR

• There is no docker rename for images - that command renames containers. For an image the rename is two commands: docker tag old:tag new:tag adds the new name, docker rmi old:tag removes the old one.
• The image ID does not change and no bytes are copied: a name is a label pointing at the same layers. docker rmi of a name that still has other names prints Untagged, not Deleted.
• Only the repository part must be lowercase; the tag may contain capitals. docker tag jhooq/web:1.0 JHOOQ/Web:1.0 fails with repository name (Web) must be lowercase.
• Retag before you push - the registry decides the shape: rahulwagh/web:1.0 for Docker Hub, ghcr.io/rahulwagh/web:1.0 for GitHub, <account>.dkr.ecr.<region>.amazonaws.com/web:1.0 for AWS ECR, host:5000/web:1.0 for a private registry (no https://).
• Registries do not rename repositories. Create the new one, push the tags under the new name, delete the old repository.
• Every output below is from Docker 28.0.4 on Ubuntu 24.04, captured on 2026-10-12.
• Not your exact case? The closest post on this site is docker.

Have you ever found yourself needing to change the repository name or rename a Docker image?

I recently faced this challenge and got to know that it is a very simple yet effective process to accomplish it. The thing which confuses most people is that there is a docker rename command - but it is for containers, not images. For images there is no rename at all. What you actually do is give the image a second name with docker tag, and then drop the old name.

In this blog post, I want to share my step-by-step process of changing the repository name and renaming Docker images. Let's dive in together!

Table of Content

1. Understanding Docker Image Names and Tags
2. Tagging the Existing Image with the New Name
3. Renaming only the tag (version) of an image
4. Retagging for a registry - Docker Hub, GitHub Container Registry, AWS ECR
5. Pushing the Newly Tagged Image
6. Removing the Old Image Name
7. Renaming the repository on the registry itself
8. What broke when I ran this
9. Conclusion

1. Understanding Docker Image Names and Tags

Before we get started, let's take a moment to understand Docker image names.

A full image name has up to four parts -

1[registry/][namespace/]repository[:tag]

• registry - Where the image is stored, e.g. docker.io (the default, so it is usually not written), ghcr.io or your AWS ECR host.
• namespace - Your Docker Hub username or organisation, e.g. rahulwagh.
• repository - The actual name of the image, e.g. myimage. This is the part people mean when they say "rename the image".
• tag - The version or variant, e.g. v1. Defaults to latest if you leave it out.

For example, I had an image called oldrepo/myimage:v1, where oldrepo is the namespace, myimage is the repository name and v1 is the tag.

Here is the key thing to understand - an image is really identified by its image ID (the sha256 hash). A name is just a label pointing at that ID, and one ID can have many labels. That is why "renaming" is really "add a new label, remove the old label", and why it takes no disk space and no rebuild.

2. Tagging the Existing Image with the New Name

To change the repository name or rename a Docker image, the first step is to tag the existing image with the new name.

Don't worry, it's easier than it sounds! Here is the command syntax -

1# Please replace the existing image name as well as the new repository name
2
3docker tag <existing_image>:<tag> <new_repository>:<tag>

In my case, I had an image named myimage in the repository oldrepo with the tag v1. I wanted to rename it to newrepo while keeping the same tag. So, the command I ran looked like this -

1# Existing repo name = oldrepo
2# New Repo name = newrepo
3# Tag = v1 (no need to change the tag)
4
5docker tag oldrepo/myimage:v1 newrepo/myimage:v1

By executing this command, I created a new name for the image with the desired repository name. (Newer Docker versions also accept docker image tag, it is exactly the same command.)

You can verify the newly renamed docker image by running the following docker command -

1# List all the docker images
2
3docker image ls

Here is the whole rename, start to finish, as Docker 28.0.4 printed it on 2026-10-12. I used the public nginx:1.27-alpine image as the "old" name and jhooq/web:1.0 as the new one -

 1$ docker image ls nginx
 2REPOSITORY   TAG           IMAGE ID       CREATED         SIZE
 3nginx        1.27-alpine   6769dc3a703c   18 months ago   48.2MB
 4
 5$ docker tag nginx:1.27-alpine jhooq/web:1.0
 6
 7$ docker rmi nginx:1.27-alpine
 8Untagged: nginx:1.27-alpine
 9Untagged: nginx@sha256:65645c7bb6a0661892a8b03b89d0743208a18dd2f3f17a54ef4b76fb8e2f2a10
10
11$ docker image ls --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.Size}}'
12REPOSITORY   TAG   IMAGE ID       SIZE
13jhooq/web    1.0   6769dc3a703c   48.2MB
14
15$ docker image inspect -f '{{.Id}}' jhooq/web:1.0
16sha256:6769dc3a703c719c1d2756bda113659be28ae16cf0da58dd5fd823d6b9a050ea

Notice the same IMAGE ID before and after (6769dc3a703c), the size (48.2MB) that was never duplicated - two names for one image is still 48.2 MB on disk, not 96.4 MB, and the rename copied 0 MB - and that docker rmi said Untagged, not Deleted - the layers stayed, only the name went. Between tag and rmi both names existed at once, which is the safe moment to check that the new name works (docker run --rm jhooq/web:1.0 nginx -v).

You can also rename the repository and the image name in one go, e.g. -

1docker tag oldrepo/myimage:v1 rahulwagh/jhooq-api:v1

Just remember the rules for a valid name - the repository part must be lowercase. If you get invalid reference format here, I have a whole post on how to fix the docker invalid reference format error.

3. Renaming only the tag (version) of an image

Quite often you do not want to change the repository at all, you just want a different tag - for example promote myimage:build-1234 to myimage:latest, or myimage:v1 to myimage:1.0.0. It is the same command -

1docker tag newrepo/myimage:v1 newrepo/myimage:1.0.0

and if you leave the tag out on the right side, Docker uses latest -

1docker tag newrepo/myimage:v1 newrepo/myimage

With the image from above, adding a latest tag and a registry-prefixed name gives three names for one ID -

 1$ docker tag jhooq/web:1.0 jhooq/web:latest
 2$ docker tag jhooq/web:1.0 ghcr.io/rahulwagh/web:1.0
 3
 4$ docker image ls --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}' | sort
 5REPOSITORY                                   TAG       IMAGE ID
 6ghcr.io/rahulwagh/web                        1.0       6769dc3a703c
 7jhooq/web                                    1.0       6769dc3a703c
 8jhooq/web                                    latest    6769dc3a703c
 9
10$ docker rmi jhooq/web:latest
11Untagged: jhooq/web:latest

The rules in one table -

4. Retagging for a registry - Docker Hub, GitHub Container Registry, AWS ECR

The most common real reason to rename an image is that you built it locally with a short name and now you want to push it somewhere. The registry decides what the name has to look like -

1. Docker Hub - <your-dockerhub-username>/<repository>:<tag>

1docker tag myimage:v1 rahulwagh/myimage:v1

2. GitHub Container Registry (ghcr.io) - ghcr.io/<github-username-or-org>/<repository>:<tag>, and the username must be lowercase

1docker tag myimage:v1 ghcr.io/rahulwagh/myimage:v1

3. AWS ECR - <account-id>.dkr.ecr.<region>.amazonaws.com/<repository>:<tag>

1docker tag myimage:v1 123456789012.dkr.ecr.eu-central-1.amazonaws.com/myimage:v1

I have a separate step-by-step guide on how to push a docker image to AWS ECR, including the login part which trips people up.

4. A self-hosted / private registry - <host>:<port>/<repository>:<tag>, no https:// in front

1docker tag myimage:v1 registry.jhooq.com:5000/myimage:v1

5. Pushing the Newly Tagged Image

Once I had tagged the image with the new repository name, the next step was to push it to the Docker registry.

This step allows me to share the image with others and deploy it easily. Here's the command syntax I used for pushing the docker image -

1# Docker push command to push the docker image
2
3docker push <new_repository>:<tag>

In my case, I executed -

1# Docker command to push docker image to newrepo
2
3docker push newrepo/myimage:v1

With this command, the image with the new repository name was uploaded to the Docker registry.

Note - Pushing requires you to be logged in to that registry (docker login, or aws ecr get-login-password ... | docker login ... for ECR). If you get denied: requested access to the resource is denied, that is a login or permission problem, not a naming problem - I have covered it in this post.

6. Removing the Old Image Name

If you prefer, you can remove the old name from your local machine. Because both names point at the same image, this only removes the label, not the image itself. To remove the old name, I used the following command -

1# Remove the old image name
2
3docker rmi <existing_image>:<tag>

For instance, I ran -

1# Remove the old image name
2docker rmi oldrepo/myimage:v1

and Docker tells you exactly what happened -

1Untagged: oldrepo/myimage:v1

It says Untagged, not Deleted - the image is still there under newrepo/myimage:v1. (docker image rm is the newer spelling of the same command.) Only when you remove the last name of an image does Docker actually delete the layers.

Two things to check before removing the old name -

1. Running containers - A container keeps a reference to the image ID it was started from, so renaming does not break running containers. But docker ps will keep showing the old name in the IMAGE column until you recreate the container. If the old name is still in use you will see conflict: unable to remove repository reference ... (must force) - container abc123 is using its referenced image - I have written about that error here.
2. Compose files, Kubernetes manifests, CI pipelines - Anything that references oldrepo/myimage has to be updated to the new name, otherwise the next docker compose up or deployment will try to pull an image that no longer exists.

7. Renaming the repository on the registry itself

Everything above renames the image locally and pushes it under the new name. But what about the old repository which already exists on Docker Hub or ECR with all its tags?

Here is the honest answer - most registries do not let you rename a repository.

• Docker Hub - There is no rename. Create the new repository, push your images under the new name, and delete the old repository from the Hub settings page once nothing depends on it.
• AWS ECR - Same story, repository names are immutable. Create the new repository (aws ecr create-repository --repository-name newrepo/myimage), re-push, and delete the old one.
• GitHub Container Registry - A package follows the repository/organisation name. Renaming the GitHub repository does not rename the package; you push to the new package name.

If the old repository has many tags you want to keep, you do not have to rebuild anything. Pull each tag, retag it, push it -

1for tag in v1 v2 v3; do
2  docker pull oldrepo/myimage:$tag
3  docker tag  oldrepo/myimage:$tag newrepo/myimage:$tag
4  docker push newrepo/myimage:$tag
5done

Or, if you do not want to download the layers to your laptop at all, crane copy from Google's go-containerregistry copies images directly between registries - for the 48.2 MB nginx image that is a 48.2 MB download plus a 48.2 MB upload saved per tag, and for a 1 GB application image it is the difference between minutes and seconds -

1crane copy oldrepo/myimage:v1 newrepo/myimage:v1

8. What broke when I ran this

I re-ran every command in this post on 2026-10-12 with Docker 28.0.4 on Ubuntu 24.04, and deliberately tried the mistakes readers report in the comments. The real error messages -

1$ docker tag jhooq/web:1.0 JHOOQ/Web:1.0
2Error parsing reference: "JHOOQ/Web:1.0" is not a valid repository/tag: invalid reference format: repository name (Web) must be lowercase
3
4$ docker tag jhooq/web:1.0 jhooq/web:1.0!
5Error parsing reference: "jhooq/web:1.0!" is not a valid repository/tag: invalid reference format
6
7$ docker tag doesnotexist:1 jhooq/web:2.0
8Error response from daemon: No such image: doesnotexist:1

1. The lowercase rule names the part that is wrong. repository name (Web) must be lowercase points at Web, not at JHOOQ, because Docker checks the path component by component. Fixing one capital letter and re-running gives you the next one. A tag with capitals (jhooq/web:V1) is fine; the full list of allowed characters is in my post on docker: invalid reference format.

2. docker image ls takes at most one repository filter. I wanted to list the old and new name side by side with docker image ls nginx jhooq/web and got 'docker image ls' requires at most 1 argument. Use --format and sort, as in the blocks above, or docker image ls --filter reference='jhooq/*'.

3. The old name is gone from the local list, but not from Docker Hub. After docker rmi nginx:1.27-alpine the nginx row disappeared locally; the public image of course still exists and docker pull nginx:1.27-alpine brings the row straight back with the same ID (6769dc3a703c), because the layers were never deleted. Renaming is local bookkeeping until you push.

The untag of nginx:1.27-alpine also printed a second line, Untagged: nginx@sha256:65645c... - that is the digest reference that docker pull records, removed together with the tag. Images you built locally do not have one.

9. Conclusion

I successfully changed the repository name and renamed my Docker image. To summarise -

1. There is no docker rename for images. docker tag old new adds the new name, docker rmi old removes the old one, and the image ID never changes.
2. The same two commands rename only the tag, or retag an image for Docker Hub, GitHub Container Registry or AWS ECR before pushing.
3. Registries do not rename repositories - create the new one, re-push the tags, delete the old one.
4. Do not forget to update every compose file, manifest and pipeline that still mentions the old name.

I hope my personal experience and step-by-step guide have been helpful to you. If you have any questions or need further assistance, please feel free to reach out in the comments. The reference for the naming rules is the docker image tag documentation, and the pushing side is in the docker push documentation. If the next thing you hit is a container that will not restart on the new name, how to restart a single container is the companion to this post.