Docker Compose Profiles

Docker Compose profiles let you keep optional services in one Compose file without starting them every time. You can place debuggers, monitoring tools, migration jobs, or local utilities behind named profiles while your core application remains available by default.

This approach keeps related configuration together and gives you a clear command for each working mode. You can start a small everyday stack, then enable extra services only when you need them.

How Docker Compose Profiles Work

Add the profiles attribute to a service and provide one or more profile names. A service without this attribute belongs to the default application model and starts normally. A profiled service starts only when you enable one of its profiles or explicitly target that service.

Example:

services:
  app:
    image: nginx:alpine
    ports:
      - "8080:80"

  debug-tools:
    image: alpine:latest
    # Keep this container running while you inspect the stack.
    command: ["sh", "-c", "echo Debug tools ready && sleep infinity"]
    profiles: ["debug"]

  metrics:
    image: alpine:latest
    # Simulate an optional monitoring service.
    command: ["sh", "-c", "echo Metrics service ready && sleep infinity"]
    profiles: ["monitoring"]

The app service has no profile, so Compose treats it as a core service. The other two services stay inactive until you select their profiles.

Start the Default Services

Run the usual command when you only need the core application:

Example:

# Start services that do not have a profile.
docker compose up -d

Output:

[+] Running 2/2
 ✔ Network project_default  Created
 ✔ Container project-app-1 Started

The exact project and container names depend on your directory and Compose configuration. The important result is that neither optional service starts.

Enable One or More Profiles

Use --profile before the Compose command. Repeat the option when you want several profiles:

Example:

# Start the core app and the debugging service.
docker compose --profile debug up -d

# Start the core app and both optional services.
docker compose --profile debug --profile monitoring up -d

You can also set COMPOSE_PROFILES to a comma-separated list. This is useful in a script or a development environment that consistently needs the same tools.

Example:

# Enable two profiles for this command.
COMPOSE_PROFILES=debug,monitoring docker compose up -d

Use --profile "*" when you intentionally want every declared profile. Avoid making this your normal command because it can start tools that consume extra memory or expose local ports.

Profile Command Behavior

Target a Profiled Service Directly

If you explicitly name a profiled service, Compose runs that service even when you do not enable its profile. This is convenient for one-off jobs such as database migrations or diagnostics.

Example:

services:
  app:
    image: nginx:alpine

  config-check:
    image: alpine:latest
    profiles: ["tools"]
    # Exit after checking the supplied configuration directory.
    command: ["sh", "-c", "test -d /config && echo Configuration found"]
    volumes:
      - ./config:/config:ro

Example:

# Run only the named one-off service and its dependencies.
docker compose run --rm config-check

Output:

Configuration found

Direct targeting does not activate every other service that shares the same profile. Enable the profile when you want the complete group.

Use Profiles with Dependencies

Compose still follows dependency rules. When a targeted or enabled service requires another service through depends_on, the dependency must be available in the active model. Give related optional services a compatible profile, or leave a shared dependency unprofiled.

Note: Keep essential services outside profiles. If the application cannot work without a database or message broker, making that dependency optional can produce confusing startup errors.

Choose Clear Profile Names

A profile name must begin with a letter or digit and can then contain letters, digits, periods, underscores, or hyphens. Names such as debug, test-data, and observability.local are valid.

Organize profiles by purpose rather than by team member. The following groups are usually easy to understand:

• debug: inspection and troubleshooting services.
• test: test runners, fixtures, or temporary dependencies.
• monitoring: metrics and log-viewing tools.
• admin: optional management interfaces.

Stop Profiled Services

Use the same profile selection when you want Compose to operate on that profile as a group. To remove the entire project, including containers created during earlier profile runs, use docker compose down.

Example:

# Stop the services in the monitoring profile.
docker compose --profile monitoring stop

# Remove containers and the default network for the project.
docker compose down

Best Practices

• Leave the minimum working application unprofiled.
• Use a profile for optional tools, not for essential dependencies.
• Document the command developers should run for each profile.
• Keep profile names stable so scripts and CI jobs do not break.
• Check the resolved model with docker compose config before troubleshooting startup behavior.

Conclusion

Docker Compose profiles make one Compose file flexible without hiding how services start. Keep core services active by default, group optional services by purpose, and enable only the profiles required for the current task. This gives you faster startup, clearer commands, and a stack that remains easier to maintain.