docker-rename

Rename a container

$ docker rename [container] [new_name]

$ docker rename --help

docker rename OLD_NAME NEW_NAME

OLD_NAME
    The current name or ID of the Docker container you wish to rename.

NEW_NAME
    The desired new name for the container. This name must be unique among all containers.

The docker rename command allows users to change the name of an already existing Docker container. This is particularly useful for organizing containers, adhering to naming conventions, or correcting misspellings without needing to stop, commit, remove, and recreate the container.

The command directly updates the container's metadata, making the change effective immediately. It does not require the container to be stopped; it can be running or stopped when renamed. This simplifies container management workflows significantly by providing a straightforward way to modify container identifiers.

The new name (NEW_NAME) must be unique among all existing containers. If a container with the NEW_NAME already exists, the command will fail.

If other containers are linked to the renamed container using the old name (via the deprecated `--link` flag), those links will become stale and will no longer resolve correctly.

For containers on user-defined networks, renaming might affect network aliases that were derived from the original name. However, the container's IP address and general network configuration typically remain unchanged.

Renaming does not affect the container's filesystem, installed applications, or running processes.

The docker rename command can be used on both running and stopped containers. The rename operation is nearly instantaneous and does not interrupt the container's running processes or network connectivity. This allows for flexible naming changes without service disruption.

Docker enforces unique names for all containers. If you attempt to rename a container to a name already in use by another container, the operation will fail with an error message indicating the name conflict. You must choose a name that is not currently assigned to any other container.

The docker rename command was introduced in Docker Engine 1.10.0 (API version 1.22) on February 9, 2016. Before its introduction, renaming a container was not directly possible through the Docker CLI, requiring users to resort to complex workarounds like stopping, committing, removing the old container, and then running a new container with the desired name from the committed image. This feature significantly simplified container management and addressed a long-standing user request.

docker ps(1), docker inspect(1), docker start(1), docker stop(1), docker rm(1), docker run(1)