Docker Compose container names

Default Compose container names

Docker Compose derives each container name from the project name, service name, and replica index: <project>-<service>-<index>. With this compose.yaml, Compose creates storefront-api-1 and storefront-db-1 by default.

name: storefront

services:
  api:
    image: nginx:alpine
  db:
    image: postgres:18-alpine

Letting Compose assign names prevents collisions between projects and gives replicas predictable numeric suffixes. The top-level version field is obsolete and is intentionally omitted from current Compose examples.

Set a fixed name with container_name

The container_name service attribute replaces the generated name with one exact value.

services:
  api:
    image: nginx:alpine
    container_name: storefront-api

A fixed name can help a human-facing local workflow, but it makes the file less reusable across project names and hosts. Docker Compose rejects an attempt to scale a service beyond one container when that service declares container_name. Prefer the default name unless an external tool truly requires a fixed container name. See the official Compose service reference.

Service names, container names, and DNS

Other containers in the same Compose app should connect to a service by its service name, not by a generated container name. In the example below, api should use http://db:5432. Compose attaches both services to a default network and keeps the stable DNS name db even when a container is recreated with a new IP.

services:
  api:
    image: example/api
    environment:
      DATABASE_HOST: db
  db:
    image: postgres:18-alpine

From the host machine, use the published host port instead of the service's internal DNS name. The official Compose networking guide explains the default network and service discovery behavior.

Compose project-name precedence

The project name namespaces generated containers, networks, and other resources. Compose chooses it using this precedence, from highest to lowest:

1. The -p command-line flag.
2. The COMPOSE_PROJECT_NAME environment variable.
3. The top-level name field in the Compose file.
4. The directory containing the first Compose file.
5. The current directory when no Compose file path is supplied.

docker compose -p preview-1842 up -d
# Creates names such as preview-1842-api-1

The official project-name guide documents the full precedence and naming constraints.

Check a proposed container_name

This validator applies Docker's container-name pattern separately from lowercase DNS-label guidance. It checks the exact input and never trims or rewrites it.

Troubleshoot container name conflicts

A conflict means the Docker host already has a container with the same exact name, including a stopped container. Identify the owner before changing anything:

docker ps -a --filter name=storefront-api
docker compose ls
docker compose ps -a

Then choose the least surprising fix: start the intended existing project, run the new app with a different project name, rename the old container, or remove a container you no longer need. Avoid immediately deleting a conflicting container when you do not know which project owns it.

docker compose -p storefront-dev up -d
docker rename storefront-api storefront-api-old

Choose names for your containers and projects

Use the Docker name generator for memorable random names, or read the broader Docker container names guide for docker run --name, validation, renaming, and naming conventions.