Skip to content

Compose: env variable clarification #25398

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aevesdocker merged 1 commit into from
Jun 19, 2026
+13 −5
Merged

Compose: env variable clarification #25398

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions content/manuals/compose/how-tos/environment-variables/variable-interpolation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,12 @@ Docker Compose can interpolate variables into your Compose file from multiple so
Note that when the same variable is declared by multiple sources, precedence applies:

1. Variables from your shell environment
2. If `--env-file` is not set, variables set by an `.env` file in local working directory (`PWD`)
3. Variables from a file set by `--env-file` or an `.env` file in project directory
2. Variables from a file set by `--env-file`
3. If `--env-file` is not set, variables from an `.env` file in the project directory,
where the project directory is:
- `--project-directory` if set
- otherwise, the directory of the first Compose file specified with `-f`/`--file`
- otherwise, your shell's current directory (`PWD`)

You can check variables and values used by Compose to interpolate the Compose model by running `docker compose config --environment`.

Expand Down Expand Up @@ -226,9 +230,13 @@ $ docker compose --env-file ./config/.env.dev up

An `.env` file can also be used to declare [pre-defined environment variables](envvars.md) used to control Compose behavior and files to be loaded.

When executed without an explicit `--env-file` flag, Compose searches for an `.env` file in your working directory ([PWD](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html#index-PWD)) and loads values
both for self-configuration and interpolation. If the values in this file define the `COMPOSE_FILE` pre-defined variable, which results in a project directory being set to another folder,
Compose will load a second `.env` file, if present. This second `.env` file has a lower precedence.
When executed without an explicit `--env-file` flag, Compose searches for an `.env` file
in the project directory and loads values both for self-configuration and interpolation.
The project directory is determined by `--project-directory` if set, otherwise by the
directory of the first Compose file specified with `-f`/`--file`, otherwise `PWD`.
If the values in this file define the `COMPOSE_FILE` pre-defined variable, which results
in a project directory being set to another folder, Compose loads a second `.env` file,
if present. This second `.env` file has a lower precedence.

This mechanism makes it possible to invoke an existing Compose project with a custom set of variables as overrides, without the need to pass environment variables by the command line.

Expand Down