Docker Compose profiles let you selectively enable/disable services within a single compose file — useful for managing optional services or different environment configurations without maintaining entirely separate compose files.
The Problem Profiles Solve
Not every service in a compose file needs to run in every context — a debugging tool, an optional admin interface, or a service only needed in development shouldn't necessarily start with your core production stack every time.
Defining Profiles
services:
app:
image: myapp:latest
ports:
- "3000:3000"
db:
image: postgres:16
adminer:
image: adminer
ports:
- "8080:8080"
profiles:
- debug
mailhog:
image: mailhog/mailhog
ports:
- "8025:8025"
profiles:
- debugServices without a profiles key always start; services with a profile only start when that profile is explicitly activated.
Starting Without Any Profile (Core Services Only)
docker compose up -dOnly app and db start — adminer and mailhog remain inactive.
Starting With a Specific Profile Activated
docker compose --profile debug up -dNow all services start, including the debug-profiled ones — useful for local development where you want database admin tools and email testing utilities, but not in production.
Activating Multiple Profiles
docker compose --profile debug --profile monitoring up -dSetting a Default Profile via Environment Variable
export COMPOSE_PROFILES=debug
docker compose up -dAvoids needing to type --profile every time during a development session.
Alternative Approach: Override Files for Environment Differences
See Docker Compose Override Files: Managing Dev vs Prod Configs for a complementary technique — profiles control which services run, while override files handle broader configuration differences (environment variables, resource limits) between environments; often used together.
Practical Use Case: Development-Only Debugging Tools
services:
redis-commander:
image: rediscommander/redis-commander
profiles:
- dev
ports:
- "8081:8081"A Redis admin GUI useful during development but never needed (or wanted) in production — profiles cleanly exclude it from production deployments while keeping it available for local use.
Practical Use Case: Optional Heavy Services
Services with significant resource requirements that aren't always needed (a full monitoring stack, a heavy analytics service) can be profile-gated, letting developers opt in only when actually working on something requiring them.
Verifying Which Services Are Active
docker compose psCommon Errors
Expected service doesn't start — verify you're activating the correct profile name, and check for typos between the profile defined in the compose file and the one specified on the command line.
Continue Reading
- Docker Compose Override Files: Managing Dev vs Prod Configs
- Docker Compose .env Files and Environment Variables Explained
- How to Set Up a Staging Environment for an E-commerce Store
Browse more articles in Docker & Containers.
