Profiles for Optional Services

profiles: and --profile

Services with a profiles list start only when one of those profiles is active (--profile debug or COMPOSE_PROFILES=debug). Services without profiles always start. Use profiles for optional tools: database admin UIs, mail catchers, load generators, test runners. This keeps the default up lean while making extras one flag away.

Services with and without a profile, run

I ran this with Docker Compose v2.38.1 and jq in the demo "shop" project. docker compose config parses, interpolates, merges and validates the files without starting containers; the Docker daemon was not running, so nothing was started. By default the project has db, api and web; activating the debug profile adds the adminer database UI.

docker compose config --services
echo "--- with the debug profile:"
docker compose --profile debug config --services

Output:

db
api
web
--- with the debug profile:
adminer
db
api
web

Document your profiles

List available profiles and what they add in the README so new developers find them.

Quick check: When does a service with profiles: ["debug"] start?

• Only in production
• Always
• Never
• Only when the debug profile is activated