Docker Compose — Compose Profiles

1 minute read

Profiles let you define services that only start when a specific profile is activated. This keeps your compose file complete but flexible.

Defining Profiles

services:
  api:
    image: myapi:latest
    ports:
      - "3000:3000"
    # No profile — always starts

  db:
    image: postgres:16
    # No profile — always starts

  adminer:
    image: adminer:latest
    ports:
      - "8080:8080"
    profiles:
      - debug             # Only starts with --profile debug

  mailhog:
    image: mailhog/mailhog
    ports:
      - "8025:8025"
    profiles:
      - debug             # Only starts with --profile debug

Starting with Profiles

# Start only default services (api, db)
docker compose up -d

# Start default + debug services (api, db, adminer, mailhog)
docker compose --profile debug up -d

Multiple Profiles

A service can belong to multiple profiles:

services:
  monitoring:
    image: prometheus:latest
    profiles:
      - monitoring
      - production

  grafana:
    image: grafana/grafana
    profiles:
      - monitoring

# Start monitoring tools
docker compose --profile monitoring up -d

# Start multiple profiles
docker compose --profile monitoring --profile debug up -d

Environment Variable Activation

COMPOSE_PROFILES=debug,monitoring docker compose up -d

Or in .env:

COMPOSE_PROFILES=debug

Rules

Rule Detail
No profile Service always starts
One profile Starts only when that profile is active
Multiple profiles Starts when ANY listed profile is active
depends_on Automatically starts profile dependencies

depends_on with Profiles

If a non-profile service depends on a profile service, Compose auto-starts it:

services:
  api:
    image: myapi
    depends_on:
      - db
  db:
    image: postgres:16
    profiles:
      - backend

docker compose up api    # Also starts db (dependency)

Summary

Feature Detail
Define profiles: [name] on service
Activate --profile name or COMPOSE_PROFILES
No profile Always starts
Multiple --profile a --profile b
Auto-start Dependencies activated automatically

Quick Reference

Item Detail
profiles: List of profile names for a service
–profile Activate at command line
COMPOSE_PROFILES Env var to activate
No profile Service always starts
depends_on Auto-activates profile dependencies

You may also enjoy