How to use Docker Compose profiles?

· Category: Docker

Short answer

Docker Compose profiles allow you to mark services as optional. Services without a profile always start, while profiled services only start when you pass --profile or set the COMPOSE_PROFILES environment variable.

Steps

  1. Add profiles to services that should be optional.
  2. Start the stack with docker compose --profile dev up -d.
  3. Set the COMPOSE_PROFILES environment variable for persistent selection.

Example

services:
  web:
    image: myapp
  db:
    image: postgres
  debugger:
    image: debug-tools
    profiles:
      - debug

Start with the debug profile:

docker compose --profile debug up -d

Or:

export COMPOSE_PROFILES=debug
docker compose up -d

Tips

  • Use profiles for development tools, test databases, and monitoring sidecars.
  • A service can belong to multiple profiles.
  • depends_on to a profiled service does not auto-start it unless the profile is active.

Common issues

  • Forgetting to pass --profile results in missing services.
  • Profile names are case-sensitive.
  • Services started with a profile will be stopped by docker compose down even if the profile is omitted.