20.2.1.2 Compose Service Names

Service names in a Docker Compose file are the keys you assign under the services section of compose.yml. They serve two purposes: they identify the service for Compose commands, and they become DNS hostnames that other containers in the same Compose network use to reach that service. Understanding service names, how they are resolved, and how they relate to container names avoids confusion when connecting services to each other.

Defining Service Names

The service name is the YAML key under services:

services:
  api:
    image: node:20-alpine
  database:
    image: postgres:15
  cache:
    image: redis:7-alpine

The service names here are api, database, and cache. These names are chosen by the developer and can be anything valid as a YAML key.

Service Names as DNS Hostnames

When Compose creates a network for the application, it registers every service name as a DNS entry. Any container in the Compose application can resolve the service name to the IP address of the corresponding container.

The api service can connect to PostgreSQL by using database as the hostname:

postgres://user:password@database:5432/mydb

And to Redis using:

redis://cache:6379

No additional network configuration is required. Compose wires the DNS entries automatically when the containers start.

Verifying DNS Resolution

To confirm that service name resolution is working, run a DNS lookup from inside a service container:

docker compose exec api nslookup database

Server:    127.0.0.11
Address:   127.0.0.11:53

Non-authoritative answer:
Name:   database
Address: 172.20.0.3

127.0.0.11 is Docker's embedded DNS server, which handles service name resolution within the Compose network. The returned address is the container's IP on the private Compose network.

Service Name vs Container Name

The service name and the container name are related but different things.

The service name is what you put in compose.yml and what other services use as a DNS hostname.

The container name is the name Docker assigns to the running container. By default, Compose constructs it as <project>_<service>_<replica_number>:

myapp-api-1
myapp-database-1
myapp-cache-1

The project name defaults to the directory containing compose.yml. Running docker ps shows container names, not service names.

You can override the container name:

services:
  database:
    image: postgres:15
    container_name: my_postgres

With container_name set, the container is named my_postgres instead of myapp-database-1. However, the DNS hostname used by other services in Compose is still database — the service name — not the container name.

Using container_name for External Access

If you have external tooling (monitoring, backup scripts, or other Docker commands) that reference a container by name, container_name provides a stable, predictable name:

docker exec my_postgres psql -U postgres

Without container_name, you would need to use the generated name myapp-database-1, which changes if the project is moved to a different directory.

Service Names and depends_on

Service names are used in depends_on to declare startup dependencies:

services:
  api:
    depends_on:
      database:
        condition: service_healthy
      cache:
        condition: service_started

The keys under depends_on must match the service names defined in the same compose.yml. Compose uses them to determine startup ordering and, with health conditions, to wait until a service is ready.

Aliases: Multiple Hostnames for One Service

A service can be reached by multiple hostnames by defining aliases on its network configuration:

services:
  database:
    image: postgres:15
    networks:
      default:
        aliases:
          - db
          - postgres

With this configuration, other services can connect to the database using database, db, or postgres as the hostname. This is useful when migrating an application to Compose — you can keep existing connection strings that reference postgres without renaming the service.

Service Names in Compose Commands

Service names are used throughout Compose CLI commands to target a specific service:

docker compose logs database

docker compose exec api sh

docker compose restart cache

docker compose stop api

docker compose up -d --build api

In each command, the service name refers to the key in compose.yml, not the container name.

Choosing Good Service Names

Service names should reflect the role of the service, not the technology (though often both coincide). Common conventions:

Short, lowercase names without hyphens or underscores are easiest to use in connection strings. Names with hyphens are valid YAML keys but must be quoted in some connection string contexts.

Service Names Across Multiple Compose Files

When using multiple Compose files (a base compose.yml and an override compose.override.yml), service names must be consistent across all files. Compose merges the files by service name — the same service key in both files means Compose applies the override's configuration on top of the base configuration for that service.

If the service is named api in compose.yml and web in compose.override.yml, Compose treats them as two separate services rather than merging them.