9.2.2.5 Compose Network Aliases

Compose network aliases provide a service with one or more additional names it can be reached by on a given network, beyond its default Compose service name, useful for compatibility with code expecting a specific hostname or for giving a service multiple meaningful names simultaneously.

Declaring an Alias

The aliases option, nested under a service's network configuration, specifies additional resolvable names for that service.

services:
  db:
    image: postgres:16
    networks:
      app-net:
        aliases:
          - database
          - primary-db

networks:
  app-net:

Other services on app-net can now reach this service using db (its Compose service name), database, or primary-db interchangeably.

Why Aliases Are Useful for Legacy or Third-Party Code

Application code or configuration that expects a database to be reachable at a specific, fixed hostname — regardless of what a Compose file happens to name the corresponding service — can be accommodated by adding that expected hostname as an alias.

services:
  db:
    networks:
      app-net:
        aliases:
          - legacy-db-host

networks:
  app-net:

This allows code hardcoded to expect legacy-db-host to function correctly, without needing that code to be modified, simply by aliasing the actual service to that expected name.

Verifying an Alias Resolves Correctly

Confirming that other services can successfully reach a service by its alias validates the configuration is working as intended.

docker compose exec api ping legacy-db-host

Why Compose Network Aliases Matter

Network aliases provide useful flexibility for situations where a fixed expected hostname, multiple meaningful names, or compatibility with existing configuration is needed, without requiring changes to either the dependent code or the Compose service's own primary name.