Docker Compose Profiles: What Gets Enabled, Tested on v5.5.1
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 did | What actually happens |
|---|---|
Service has no profiles: | Always enabled, whatever profiles you pass |
--profile backend,debug | Treated as one profile literally named backend,debug, so nothing matches. Use two --profile flags |
COMPOSE_PROFILES=backend,debug | This 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 debug | No 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 off | config fails: depends on undefined service |
| Profiles in an override file | Appended to the base list, not replaced. !reset [] makes the service always-on |
extends: a service with profiles | The 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:
- Put both services in the same profile (or give
dbboth profiles). - Take
dbout of profiles so it’s always enabled. - 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
- Run
docker compose config --profilesand compare the names, including case, with what you’re passing. - Using a comma? Only
COMPOSE_PROFILESsplits on commas. With flags, repeat--profile. - Look for
COMPOSE_PROFILESin your shell (echo $COMPOSE_PROFILES) and in the project’s.env. Any--profileflag replaces it entirely. - Getting
depends on undefined service? The dependency’s profile is off. Enable it, share the profile, or addrequired: false. - 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 jsonshows 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>orrun <service>auto-enables that service’s profile (the docs say it does). - What
docker compose downstops. The docs say plaindownonly stops services without a profile, and--profile debug downstopsdebugservices plus the unprofiled ones. I haven’t checked whether--profile '*' downstops 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.