`docker compose config` Is How You Stop Guessing What Compose Will Really Run After Overrides and Env Substitution

Why this command matters: a Compose file is often not the final truth. By the time multiple -f files, profiles, environment substitution, and short syntax expansion are applied, what Docker actually sees can be very different from the YAML you think you wrote.

What docker compose config does

The Docker docs describe docker compose config as parsing, resolving, and rendering the Compose file in canonical format. The reference says it renders the actual data model to be applied on the Docker Engine, merges files set by -f, resolves variables, and expands short notation.

A simple example:

docker compose config

That gives you the normalized configuration Compose will actually use.

This matters because a lot of Compose confusion is not about containers at all. It is about developers debugging the wrong configuration view.

Why the raw YAML often lies by omission

Teams commonly work with:

1. compose.yaml
2. compose.override.yaml
3. profile-specific services
4. .env or alternate env files

The problem is that reading one file at a time does not tell you the final merged result. Developers then make statements like:

1. “the port is exposed”
2. “the env var is set”
3. “this service is definitely included”
4. “the volume path looks right”

Sometimes those statements are wrong because the final composed model differs from the file they were staring at.

docker compose config is the fastest way to stop arguing with assumptions and inspect the resolved truth.

A practical debugging example

Suppose an app cannot connect to Redis in dev, and your team has base and override compose files. Before changing code, run:

docker compose -f compose.yaml -f compose.dev.yaml config

Now you can verify:

1. service names
2. networks
3. image or build config
4. interpolated environment values
5. mounted paths

This is much safer than inferring runtime shape from scattered YAML fragments.

Useful options worth knowing

The Docker docs list several high-value options:

1. -q, --quiet to validate configuration without printing it
2. --services to print only service names
3. --profiles to print profile names
4. --environment to print environment used for interpolation
5. --format json for machine-readable output

These are genuinely practical.

For example, this is good in CI:

docker compose config --quiet

And this is great for scripting:

docker compose config --format json

Why this helps environment-variable debugging

Environment interpolation mistakes are among the most annoying Compose problems because the YAML can look correct while the resolved value is wrong or missing.

The docs explicitly call out that config resolves variables unless you disable interpolation. That means it is the right command when you need to answer:

1. what value did Compose actually inject
2. which variables are being used
3. did the override file win
4. are defaults being applied

These are model questions, not container questions.

Why this is better than just running up

Many developers use docker compose up as a validation step. The problem is that it mixes configuration validation with container lifecycle side effects. If your goal is simply to confirm the model, config is a much cleaner and cheaper first move.

Good debugging often means separating questions:

1. is the config valid
2. is the resolved model what I intended
3. do the containers behave correctly once started

docker compose config helps answer the first two without jumping straight into the third.

Final recommendation

When a Compose setup behaves differently from what you expected, inspect the resolved model before touching application code. docker compose config is one of the fastest ways to catch bad merges, wrong interpolation, and misleading assumptions about what Compose will actually run.

Sources

• Docker docker compose config reference