Toolarity

Docker Compose Profiles: What Gets Enabled, Tested on v5.5.1

Fix Docker Compose Published November 5, 2026

Profiles look simple: tag a service with profiles: [debug], and it only runs when you ask for debug. Then you run docker compose --profile backend,debug up and only web starts. Or a .env file quietly turns on a profile nobody remembers setting. Or Compose refuses to start at all with depends on undefined service.

I tested every rule below on Docker Compose v5.5.1 with docker compose config --services, which lists exactly the services Compose would work with after applying profiles, and doesn’t need a running Docker daemon. To prove that, every command ran with DOCKER_HOST pointed at a socket that doesn’t exist; docker compose ps fails immediately in that setup, config doesn’t. Every output below is copied from a real terminal.

Short answer (Docker Compose v5.5.1, tested 2026-09-29):

What you didWhat actually happens
Service has no profiles:Always enabled, whatever profiles you pass
--profile backend,debugTreated as one profile literally named backend,debug, so nothing matches. Use two --profile flags
COMPOSE_PROFILES=backend,debugThis one does split on commas (spaces after the comma are fine)
--profile plus COMPOSE_PROFILES (shell or .env)--profile replaces the variable, it doesn’t add to it
--profile nope or --profile Debug for debugNo error, no warning, nothing enabled. Names are case-sensitive
--profile '*'Enables every profile. Quote the * or your shell expands it
An enabled service depends_on a service whose profile is offconfig fails: depends on undefined service
Profiles in an override fileAppended to the base list, not replaced. !reset [] makes the service always-on
extends: a service with profilesThe child inherits the profiles

The test file

Most examples use this compose.yaml. adminer sits in two profiles on purpose:

services:
  web:
    image: nginx:alpine
  db:
    image: postgres:16
    profiles: [backend]
  adminer:
    image: adminer
    profiles: [debug, backend]
  mailhog:
    image: mailhog/mailhog
    profiles: [debug]

config --services prints services in a different order on each run, so every command below is piped through sort.

The basics, confirmed

No profile given: only the service without profiles: is enabled.

$ docker compose config --services | sort
web

Each profile adds its own services on top of web. A service in two profiles shows up when either one is enabled:

$ docker compose --profile debug config --services | sort
adminer
mailhog
web
$ docker compose --profile backend config --services | sort
adminer
db
web
$ docker compose --profile debug --profile backend config --services | sort
adminer
db
mailhog
web

To see which profile names exist in a project, there’s a flag for that:

$ docker compose config --profiles
backend
debug

Gotcha 1: --profile backend,debug enables nothing

The docs show two ways to enable several profiles: repeat --profile, or put a comma-separated list in COMPOSE_PROFILES. They don’t mix. A comma inside --profile isn’t split:

$ docker compose --profile backend,debug config --services | sort
web

Compose looked for a profile called backend,debug, found none, and said nothing. The same list in the environment variable works, even with a space after the comma:

$ COMPOSE_PROFILES=backend,debug docker compose config --services | sort
adminer
db
mailhog
web
$ COMPOSE_PROFILES="backend, debug" docker compose config --services | sort
adminer
db
mailhog
web

Gotcha 2: a wrong profile name fails silently

There’s no “unknown profile” error. A typo and a wrong case both just give you the always-on services:

$ docker compose --profile nope config --services | sort
web
$ docker compose --profile Debug config --services | sort
web

If a profile “does nothing”, compare what you typed against docker compose config --profiles before anything else.

Gotcha 3: --profile replaces COMPOSE_PROFILES, including the one in .env

COMPOSE_PROFILES is read from the project’s .env file too, not just your shell. Same compose.yaml as above, plus this .env:

$ cat .env
COMPOSE_PROFILES=debug
$ docker compose config --services | sort
adminer
mailhog
web

So debug is on by default for anyone who clones the repo. Now add a --profile:

$ docker compose --profile backend config --services | sort
adminer
db
web

mailhog is gone. --profile backend didn’t add to debug, it replaced it. The same happens when the variable comes from the shell:

$ COMPOSE_PROFILES=backend docker compose --profile debug config --services | sort
adminer
mailhog
web

A shell variable also beats .env, and an empty one switches the .env default off:

$ COMPOSE_PROFILES=backend docker compose config --services | sort
adminer
db
web
$ COMPOSE_PROFILES= docker compose config --services | sort
web

Docker’s profiles page and its pre-defined environment variables page both describe --profile and COMPOSE_PROFILES, but neither says which wins when you use both. The “replace, not merge” behavior above is what v5.5.1 did in my tests, not something the docs promise.

Gotcha 4: --profile '*' needs quotes

The docs say --profile "*" enables every profile, and it does:

$ docker compose --profile '*' config --services | sort
adminer
db
mailhog
web

Leave the quotes off and your shell replaces * with the file names in the current directory before Compose ever sees it. In my test folder that turned the command into --profile compose.yaml, which silently matched nothing (see Gotcha 2).

Gotcha 5: depending on a service whose profile is off breaks config

This is where profiles stop being silent. Here web has no profile, but it depends on db, which does:

services:
  web:
    image: nginx:alpine
    depends_on: [db]
  db:
    image: postgres:16
    profiles: [backend]
$ docker compose config --services
service "web" depends on undefined service "db": invalid compose project
$ echo $?
1

Once backend is enabled, db exists again and the error goes away:

$ docker compose --profile backend config --services | sort
db
web

The same thing happens between two profiles. With adminer in debug depending on db in backend, enabling only debug fails:

$ docker compose --profile debug config --services
service "adminer" depends on undefined service "db": invalid compose project
$ docker compose --profile debug --profile backend config --services | sort
adminer
db
web

Three ways out, depending on what you actually want:

  1. Put both services in the same profile (or give db both profiles).
  2. Take db out of profiles so it’s always enabled.
  3. Mark the dependency optional with required: false:
services:
  web:
    image: nginx:alpine
    depends_on:
      db:
        condition: service_started
        required: false
  db:
    image: postgres:16
    profiles: [backend]
$ docker compose config --services | sort
web
$ docker compose --profile backend config --services | sort
db
web

Gotcha 6: naming a service doesn’t enable its profile in config

Docker’s docs say that when you explicitly target a service on the command line, Compose runs it whether or not its profile is enabled. That’s about up and run. config doesn’t do it:

$ docker compose config --services db | sort
web

db wasn’t enabled just because I named it. So you can’t use config to preview what docker compose up db will start. I didn’t run up or run for this article (no daemon), so the targeted-service behavior itself is the docs’ claim, not something I checked.

Gotcha 7: override files append profiles, they don’t replace them

Base file has tools in debug. The compose.override.yaml next to it says:

services:
  tools:
    profiles: [prod]

You might expect tools to move from debug to prod. It ends up in both:

$ docker compose --profile debug config --format json | jq -c .services.tools.profiles
["debug","prod"]
$ docker compose --profile prod config --services | sort
tools
web

That matches how Compose merges other lists. To actually clear the list, use !reset. With profiles: !reset [] in the override, tools has no profiles left and is always on:

$ docker compose config --services | sort
tools
web

Gotcha 8: extends: carries profiles along; include: keeps them

A service that extends: a profiled service gets its profiles too:

services:
  base:
    image: nginx:alpine
    profiles: [tools]
  child:
    extends: base
$ docker compose config --services | sort
$ docker compose --profile tools config --services | sort
base
child

The first command prints nothing at all: with no profile enabled, this project has zero services, and config still exits 0. If child should always run, reset the inherited list on the child:

  child:
    extends: base
    profiles: !reset []
$ docker compose config --services | sort
child

Services pulled in with include: keep their profiles as written in the included file. A db in backend inside sub/compose.yaml stayed hidden until --profile backend, same as if it were in the main file.

Gotcha 9: profile names aren’t validated

Both the docs and the Compose Spec say profile names must match [a-zA-Z0-9][a-zA-Z0-9_.-]+. v5.5.1 doesn’t enforce that. All of these were accepted, and the one with a space can even be enabled:

$ docker compose config --profiles
-bad
Debug
a
debug tools
$ docker compose --profile 'debug tools' config --services | sort
spaced
web

Don’t rely on that; a later version could start rejecting them. What is checked is the type. profiles: debug (a string instead of a list) fails:

$ docker compose config --services
validating /path/to/compose.yaml: services.web.profiles must be a array

(Path shortened; the rest is verbatim.)

What I’d check, in order

  1. Run docker compose config --profiles and compare the names, including case, with what you’re passing.
  2. Using a comma? Only COMPOSE_PROFILES splits on commas. With flags, repeat --profile.
  3. Look for COMPOSE_PROFILES in your shell (echo $COMPOSE_PROFILES) and in the project’s .env. Any --profile flag replaces it entirely.
  4. Getting depends on undefined service? The dependency’s profile is off. Enable it, share the profile, or add required: false.
  5. A service in an unexpected profile? Check override files and extends:: both can add profiles you didn’t write in the service itself. docker compose config --format json shows the final list.

Test setup and what this doesn’t cover

Docker Compose v5.5.1 (docker compose version), Docker CLI 29.8.0, on macOS 15.3.1, tested 2026-09-29. Every claim above was checked with docker compose config, with DOCKER_HOST set to a nonexistent socket so nothing could reach a daemon. I didn’t run up, run, or down, and didn’t start Docker Desktop.

Not tested, so not claimed here:

  • Whether docker compose up <service> or run <service> auto-enables that service’s profile (the docs say it does).
  • What docker compose down stops. The docs say plain down only stops services without a profile, and --profile debug down stops debug services plus the unprofiled ones. I haven’t checked whether --profile '*' down stops everything, though it would follow from the rules above.
  • Windows and Linux hosts, and Compose versions before v5.5.1.

Official docs checked 2026-09-29, from their source on GitHub: Docker’s “Using profiles with Compose” and “Pre-defined environment variables” pages, and the profiles section of the Compose Spec’s services reference. Where this article goes beyond them (comma handling in --profile, replace-not-merge, the missing name validation) it says so rather than presenting it as documented behavior.

For the other two things that most often make Compose ignore your settings, see why your .env isn’t loading and why your override file isn’t working.