Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Docker Compose ignores the values in my env file

Errora ${VARIABLE} in compose.yaml becomes an empty string

Short answer

Compose has two separate env mechanisms. The env_file attribute feeds the container's environment. The .env file (or --env-file) feeds ${VAR} substitution inside compose.yaml. Mixing them up is the usual cause. Run docker compose config to see the final values Compose will really use.

  • Applies to Docker Compose 2.40, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the configuration Compose will apply. It shows each service's final environment and every substituted ${VAR}, so you see the problem before starting anything.

    docker compose config
  2. 2Match what you see, then jump to its fix

    1. 1Compose warns the variable is unset, or an image tag or port ends up blank, although the name is in your env_file${VAR} in compose.yaml is read from .env, not from env_fileFix
    2. 2The variables are missing, and the entry has required: false so Compose skipped the file without a wordThe env_file path is resolved from the wrong placeFix
    3. 3The variable is set, but to a different value than the one in the fileAnother source has higher precedence than the env fileFix
    4. 4Variables that worked before disappear after you add --env-file to the command--env-file replaced the default .envFix

What does the error look like?

  • a ${VARIABLE} in compose.yaml becomes an empty string
  • the variable is empty inside the container
  • a value from the env file is replaced by another value

Cause 1 of 4

${VAR} in compose.yaml is read from .env, not from env_file

1Check

Compose fills ${VAR} in the Compose file from your shell or the project .env file. The env_file attribute only sets variables inside the container. Show what Compose used for substitution.

docker compose config --environment

2Fix

Put variables used with ${VAR} in the .env file next to compose.yaml, or pass the file you want with --env-file. Keep env_file for variables the application reads at runtime.

# compose.yaml
services:
  db:
    image: postgres:${POSTGRES_VERSION}
    env_file: ./db.env

# .env (next to compose.yaml)
POSTGRES_VERSION=17

3Verify

The rendered image tag is complete.

docker compose config | grep image

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 4

The env_file path is resolved from the wrong place

1Check

Relative paths in env_file are resolved from the folder that holds the Compose file, not from the folder where you typed the command. Check the file is where the path says.

docker compose config | head -n 20
ls -l ./db.env

2Fix

Fix the path so it is relative to compose.yaml. If an entry has required: false, remember that a missing file is ignored without any message.

services:
  web:
    env_file:
      - path: ./web.env
        required: true

3Verify

The variables appear under the service's environment in the rendered config.

docker compose config

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 4

Another source has higher precedence than the env file

1Check

A value in the environment attribute beats env_file. With several env_file entries, a later file beats an earlier one. docker compose run -e beats everything.

grep -n -B2 -A6 "environment\|env_file" compose.yaml

2Fix

Keep each variable in one place. If you want to override, order the files so the one that should win comes last.

services:
  web:
    env_file:
      - ./common.env
      - ./production.env   # wins over common.env

3Verify

Check the final value in the rendered config.

docker compose config | grep -A10 environment

Confirmed by docs.docker.com

Did this fix it?

Cause 4 of 4

--env-file replaced the default .env

1Check

The --env-file option replaces the default .env instead of adding to it, and its path is relative to the current directory. Pass --env-file more than once to use several files; later ones win.

docker compose --env-file .env --env-file .env.production config --environment

2Fix

List every file you need, base file first, or move all values into one file.

docker compose --env-file .env --env-file .env.production up -d

3Verify

The values appear in the --environment output.

docker compose --env-file .env --env-file .env.production config --environment

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Decide per variable: used with ${VAR} in compose.yaml goes in .env; read by the app goes in env_file.
  • Run docker compose config in CI so an unset variable shows up as a diff, not as a runtime bug.
  • Do not set the same variable in both environment and env_file.
  • Use ${VAR:?error message} for values that must exist so Compose stops instead of using a blank string.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.