From 7eb60d076db1ed8fc5edc2fe8f4a78a188a16925 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Fri, 19 Jun 2026 12:46:58 +0100 Subject: [PATCH] Compose: env variable clarification Signed-off-by: aevesdocker --- .../variable-interpolation.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md b/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md index 74140869546f..7ba0d5dfa0f1 100644 --- a/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md +++ b/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md @@ -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`. @@ -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.