Docker container names

Name a container with docker run --name

Pass --name before the image name when you create a container. A chosen name is easier to use in commands than a generated container ID.

docker run --name my-container -d nginx
docker logs my-container
docker stop my-container

Container names must be unique on the same Docker host. If my-container already exists, remove or rename that container, or choose another name. The Docker name generator creates ready-to-copy names and commands.

Automatic Docker names

When you omit --name, Docker assigns a human-readable name such as focused_turing or serene_hopper. The name combines an adjective and the surname of a notable scientist or hacker. It is convenient for temporary containers, while an explicit name is usually clearer in scripts and long-lived environments.

Docker container name rules and validator

Docker accepts a letter or number first, followed by one or more letters, numbers, underscores, periods, or hyphens. In regular-expression form, the rule is ^[A-Za-z0-9][A-Za-z0-9_.-]+$.

Docker validity and DNS friendliness are different. Lowercase names containing only letters, numbers, and internal hyphens are the safest choice for hostnames. A single DNS label can be at most 63 characters.

Rename a Docker container

Use docker rename with the current name or container ID and the new name. The command also works while a container is running.

docker rename old-api-name new-api-name
docker ps --filter name=new-api-name

Renaming changes Docker's container name, not configuration stored inside the container. Update scripts or monitoring rules that refer to the old name. See the official docker container rename reference.

Container naming conventions and examples

A useful convention describes the app, role, and environment without duplicating information already managed elsewhere. Keep names short, stable, lowercase, and predictable when humans or scripts will type them.

• billing-api — app and role
• billing-worker-staging — app, role, and environment
• preview-1842 — temporary environment plus identifier
• admiring_curie — memorable Docker-generated style
• focused-hopper — random but DNS-friendly style

Do not encode mutable details such as an image patch version in a container name unless your deployment process intentionally manages that lifecycle.

Dash versus underscore

Docker's automatic names use an underscore, as in quirky_einstein. A dash produces quirky-einstein, which is friendlier for DNS labels, subdomains, and preview URLs. Both separators are valid in Docker container names, but underscores are not valid in ordinary hostname labels.

How random Docker names are generated

Docker's generator randomly picks one adjective and one surname, then joins them with an underscore. This site uses the same 108 adjectives and 236 surnames from the Moby source. That produces 25,488 raw pairs. Docker skips boring_wozniak, leaving 25,487 names that can actually be generated.

adjective + "_" + surname
// admiring_curie

The vocabulary is attributed to Docker's open source implementation in the Moby project: names-generator.go. Generate a batch with the Docker name generator.

Docker Compose container names

Docker Compose normally builds container names from the project, service, and replica number. Before setting container_name, learn how that affects scaling and service discovery in the Docker Compose container names guide.