Compose Clinic
Guides / File paths · 04

File paths · 04

Which .env is read when you use docker compose -f?

Three paths that look similar are resolved from different places. Make the input explicit and verify the resulting model.

Model checkedCompose 5.3.012 Sep 20266 min

On the version we checked

With Compose 5.3.0, our -f project/compose.yaml command used project/.env by default. An explicit --env-file cli.env was relative to the caller’s directory. The service’s env_file: config/service.env was relative to the Compose file.

Path behavior is worth recording with the version. Do not assume an older tutorial or another Compose implementation reproduces this exact fixture.

The directory layout

scratch/                 # run commands here
  .env                   # CC_WHICH=caller
  cli.env                # CC_WHICH=explicit-caller-file
  project/
    .env                 # CC_WHICH=project
    compose.yaml
    config/
      service.env        # CC_SERVICE_PATH=relative-to-compose-file

The Compose file contains:

services:
  probe:
    image: busybox:1.37
    env_file: config/service.env
    environment:
      CC_WHICH: ${CC_WHICH:-fallback}

Use fresh fixture variables, with no shell export of CC_WHICH. Run both commands from scratch/.

Compare the two successful commands

docker compose -f project/compose.yaml config

Measured result: CC_WHICH=project, plus CC_SERVICE_PATH=relative-to-compose-file.

docker compose --env-file cli.env -f project/compose.yaml config

Measured result: CC_WHICH=explicit-caller-file, with the same CC_SERVICE_PATH. Selecting the interpolation file did not relocate the service environment file.

Why this similar-looking command fails

docker compose --env-file config/service.env -f project/compose.yaml config

There is no scratch/config/service.env. Our command exited with couldn’t find env file; it did not reinterpret this CLI argument as a path under project/.

If that service file really is also your intended model input, its explicit CLI path from this directory would be project/config/service.env. Usually a dedicated model-input file makes the separation clearer.

Make a script reproducible

  1. Record docker compose version.
  2. Choose and record the script’s working directory.
  3. Use an explicit Compose path and interpolation-file path.
  4. Check the resulting model before any deployment command.

An absolute --env-file path is useful when the caller’s directory can vary. This experiment does not cover multiple merged Compose files, COMPOSE_FILE redirection, --project-directory overrides or Swarm. Those change the question and need their own fixture. No container or existing service was changed.

Sources & evidence

Documentation checked 12 Sep 2026. Our fixture evidence:

Continue the investigation