9.3.5 Compose Profiles

Compose profiles let a Compose file define services that only start when their profile is explicitly activated, allowing a single file to represent both an application's core, always-needed services and a range of optional, situational ones.

Declaring and Activating Profiles

A service is tagged with one or more profiles via its profiles field; that service only starts as part of a docker compose up when at least one of its profiles is explicitly activated.

services:
  api:
    build: .
  seed-data:
    build: .
    command: npm run seed
    profiles:
      - seeding

docker compose up -d
docker compose --profile seeding up -d

The first command starts only api; the second additionally starts seed-data, since the seeding profile was explicitly activated.

Activating Multiple Profiles Simultaneously

More than one profile can be activated together, including every service tagged with any of them.

docker compose --profile seeding --profile debugging up -d

Setting a Default Active Profile Through an Environment Variable

Rather than specifying --profile on every invocation, an environment variable can set a default that applies automatically.

export COMPOSE_PROFILES=debugging
docker compose up -d

Services Without Any Profile Always Start

A service with no profiles field at all is treated as part of every startup, regardless of which (if any) profiles are activated — profiles only affect services that explicitly opt into being conditional.

services:
  db:
    image: postgres:16

Why Compose Profiles Matter

Profiles allow a single Compose file to comprehensively represent an application's full range of services — core and optional alike — without forcing every situational or debugging-oriented service to run during ordinary, everyday use, keeping a single source of truth without unnecessary complexity in typical usage.