Rename Docker image references and containers

An image does not have one permanent name to rename. docker tag adds or moves a reference to existing image content. A container, by contrast, has a name that you can change directly with docker rename.

Add the new image reference

docker image tag myapp:1.0 registry.example.com/team/myapp:1.0
docker image inspect --format '{{.Id}}' myapp:1.0
docker image inspect --format '{{.Id}}' registry.example.com/team/myapp:1.0

Both local references should identify the intended content. Adding a tag does not make a second copy of all the image's layers. It also does not upload anything to the named registry.

After checking the replacement, remove the old local reference if it is no longer needed:

docker image rm myapp:1.0

With another tag still referencing the image, this normally removes the selected tag rather than the shared content. Image removal can also remove image data where allowed, and force-removal rules differ according to the remaining references and containers. Do not describe every rmi operation as a harmless alias deletion.

Publish or move a latest tag

To publish the registry-qualified reference, authenticate to the correct registry and use:

docker image push registry.example.com/team/myapp:1.0

To make latest identify a reviewed local version:

docker image tag myapp:1.2 myapp:latest

The assignment replaces the local latest reference. Do not then delete myapp:latest as an imagined “old latest”: that would delete the new reference you just created. Publishing the moved tag is a separate push, and already-running containers do not automatically switch images.

Rename a container

docker rename old-name new-name

A running container can be renamed without restarting its application. Its ID, image, and existing runtime settings remain. Name-based scripts, monitoring, DNS expectations, and operational procedures may still be affected, so update dependent references deliberately. A rename does not necessarily change the container's configured hostname.

For Compose-managed services, change the deployment source and let Compose manage identity. A manual rename does not rewrite the service definition or its labels and may confuse later reconciliation.

FAQ

What if removing an image fails because a container uses it?

Inspect which reference and container are involved. Do not stop or force-remove a working service merely to tidy a label. Decide whether removing that particular tag is necessary and review Docker's removal rules.

How do I migrate many registry references?

Generate an explicit source-to-destination mapping, excluding missing tags and unrelated registry names. Review it, tag each source, push each destination, and verify registry availability before removing old references. A substring replacement across every displayed image can retag the wrong repository.

Does deleting a local tag delete it from the registry?

No. Local image storage and registry tag management are separate operations.

See image tag, image rm, and container rename.