Docker Compose ignores the values in my env file
a ${VARIABLE} in compose.yaml becomes an empty stringShort 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.
Fix it fast
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 config2Match what you see, then jump to its fix
- 1
Compose 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
The 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
The variable is set, but to a different value than the one in the fileAnother source has higher precedence than the env fileFix - 4
Variables that worked before disappear after you add --env-file to the command--env-file replaced the default .envFix
- 1
What does the error look like?
a ${VARIABLE} in compose.yaml becomes an empty stringthe variable is empty inside the containera 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 --environment2Fix
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=173Verify
The rendered image tag is complete.
docker compose config | grep imageConfirmed by docs.docker.com
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.env2Fix
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: true3Verify
The variables appear under the service's environment in the rendered config.
docker compose configConfirmed by docs.docker.com
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.yaml2Fix
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.env3Verify
Check the final value in the rendered config.
docker compose config | grep -A10 environmentConfirmed by docs.docker.com
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 --environment2Fix
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 -d3Verify
The values appear in the --environment output.
docker compose --env-file .env --env-file .env.production config --environmentConfirmed by docs.docker.com
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
Servers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fix