Rename a Docker Container Without Losing Track of It

You will rename an existing Docker container, confirm that the new name resolves to the same container, and keep a simple recovery path if another command still refers to the old name. The installed Docker CLI here is docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble, and the examples use the syntax documented by that release.

Allow about ten minutes. You need access to the Docker daemon and the name or ID of a container. The rename command does not need sudo because of its syntax, but your account must be allowed to use the daemon socket. If that normally means sudo docker on your host, use it consistently for every Docker command in this guide.

1. Check the command before changing anything

Read the local command help. This is an ordinary, read-only check:

$ docker container rename --help
Usage:  docker container rename CONTAINER NEW_NAME

Rename a container

The command takes exactly two positional values: the existing container reference, followed by the replacement name. A container reference can be its current name or an ID. The command also has the shorter alias docker rename, but the full form makes scripts and runbooks clearer.

$ OLD_NAME='web-preview'
$ NEW_NAME='web-preview-old'
$ docker container inspect --format '{{.Name}}' "$OLD_NAME"
/web-preview

If inspection fails with a no-such-container error, stop and correct the reference. Do not guess from a truncated listing. To see stopped containers as well as running ones, use:

$ docker container ls --all
CONTAINER ID   IMAGE   COMMAND   CREATED   STATUS   PORTS   NAMES

The rows on your host will differ. The NAMES column is the value you can use as OLD_NAME.

2. Check that the replacement name is free

Docker names are identifiers, so a useful name must not already belong to another container. Check the proposed destination before the rename:

$ docker container inspect --format '{{.Name}}' "$NEW_NAME"
Error response from daemon: No such container: web-preview-old

A non-zero result here is expected when the destination is unused. The exact wording can vary with the daemon, so the useful fact is that inspection did not find a container with that name. If it does find one, choose a different value. Do not remove the other container just to make room.

3. Rename the container

Renaming changes the Docker name only. The container's filesystem, image, ID and configured command are not replaced by this operation. It can be running, paused or stopped, but changing the name can disrupt scripts, monitoring rules, Compose references or operator commands that still use the old name.

$ docker container rename "$OLD_NAME" "$NEW_NAME"
$ echo "rename exit status: $?"
rename exit status: 0

Successful Docker CLI output is normally empty. The zero exit status is the useful result. A running container continues running; this command does not restart it or stop its processes.

4. Verify the new name and the original identity

Ask Docker to resolve the new name and print the container ID:

$ docker container inspect --format 'name={{.Name}} id={{.Id}} status={{.State.Status}}' "$NEW_NAME"
name=/web-preview-old id=CONTAINER_ID status=running

Replace CONTAINER_ID with the value printed by your daemon. The status may instead be paused, created, exited or another valid state. The important checks are that the name has the leading slash shown by Docker and that the ID is the same one you recorded before the change.

You can also confirm that the old reference no longer resolves:

$ docker container inspect "$OLD_NAME"
Error response from daemon: No such container: web-preview

This is an expected failure after a successful rename. Any logs, volumes, networks and processes remain associated with the container; references that use the old name simply need updating.

5. Undo the rename if a dependent command needs the old name

Renaming back uses the same operation in reverse. This does not restore a deleted container because the container was never deleted:

$ docker container rename "$NEW_NAME" "$OLD_NAME"
$ docker container inspect --format '{{.Name}}' "$OLD_NAME"
/web-preview

If the old name has since been claimed by another container, do not force the change. Identify the conflicting container, choose a temporary free name if your maintenance plan permits it, and update the affected automation deliberately. A rename is not a safe way to resolve an unknown naming conflict during an outage.

6. Update callers after a deliberate rename

Search deployment files, shell scripts, monitoring checks and documentation for the old name. A command such as docker logs web-preview or docker exec web-preview ... will fail after the rename even though the container is healthy. Prefer the new name, or use the stable container ID where a name is not required. If a Compose or orchestration file owns the name, change that source configuration and follow its normal deployment procedure rather than relying on a manual rename.

Do not treat a successful rename as proof that an application has recovered. Verify the caller that motivated the change, and check the service's own health separately. The Docker rename command reports the naming operation, not the application state.