It is a standard Docker pattern: keep your baseline configuration in an .env file and pass -e flags at runtime to tweak specific settings. When both define the same variable, which value actually makes it into the container?
The Short Answer
-e wins. Whenever both --env-file and -e define the same variable, Docker prioritizes the explicit -e flag—even if --env-file appears later in the command.
Suppose app.env contains:
APP_MODE=development And you start a container with:
docker run --rm \ --env-file app.env \ -e APP_MODE=production \ alpine printenv APP_MODE Docker outputs:
production This is intentional: file-based configs act as defaults, while CLI flags act as explicit runtime overrides.
How Docker Loads Environment Variables
Docker gives you three main ways to pass environment variables into a container:
- Dockerfile
ENV: Bakes default values directly into the image (ENV APP_MODE=development). Every container started from that image inherits them unless overridden at runtime. -
--env-file: Loads bulk key-value pairs from a file on the host (docker run --env-file app.env ...). -
-e(or--env): Sets or overrides individual variables directly on the command line (docker run -e APP_MODE=production ...).
Testing the Precedence Rules
Create a sample app.env file with three variables:
cat > app.env <<'EOF' APP_MODE=development LOG_LEVEL=info APP_PORT=8080 EOF Now run a container using that file while overriding two of the variables with -e:
docker run --rm \ --env-file app.env \ -e APP_MODE=production \ -e LOG_LEVEL=warning \ alpine sh -c 'printenv APP_MODE LOG_LEVEL APP_PORT' Output:
production warning 8080 | Variable | app.env | -e Flag | Final Value in Container |
|---|---|---|---|
APP_MODE | development | production | production |
LOG_LEVEL | info | warning | warning |
APP_PORT | 8080 | (not set) | 8080 |
Docker keeps anything left untouched in the file and swaps out only the keys explicitly passed via -e.
Watch out for bare
-eflags:-e APP_MODE=productionassigns an explicit value, whereas-e APP_MODE(with no=) tells Docker to pull the variable from your host shell. IfAPP_MODEisn't exported in your current shell session, it remains unset inside the container—and won't override--env-file.
The Precedence Hierarchy
For standard docker run commands, explicit assignments resolve in this order:
| Priority | Source |
|---|---|
| 1 (Highest) | docker run -e KEY=value |
| 2 | docker run --env-file |
| 3 (Lowest) | Dockerfile ENV |
If you pass multiple --env-file flags in a single command, Docker evaluates them in order—later files override earlier ones—and -e KEY=value still overrides all of them.
How Docker Compose Differs
Docker Compose follows the same general rule—the environment block overrides env_file—but adds a few layers that frequently trip people up.
Given app.env with APP_MODE=development and this compose.yml:
services: app: image: alpine:latest env_file: - ./app.env environment: APP_MODE: production command: ["printenv", "APP_MODE"] Running docker compose run --rm app outputs production because environment takes precedence over env_file (and docker compose run -e overrides both).
Keep two Compose-specific behaviors in mind:
-
.envvs.env_file: A project-level.envfile in your working directory is used for variable interpolation insidecompose.yml(such asAPP_MODE: ${APP_MODE}). Unlikeenv_file, it does not automatically inject all of its variables into your containers. - Interpolation: Compose supports
${VAR}variable interpolation inside files loaded viaenv_file. Plaindocker run --env-filedoes not—it passes strings literally.
A Common Production Gotcha
Imagine an app deployed via a systemd unit or CI script like this:
docker run -d \ --name webapp \ --env-file production.env \ -e DEBUG=true \ mycompany/webapp:latest Inside production.env, everything looks right:
APP_MODE=production DEBUG=false LOG_LEVEL=warning An engineer checks production.env, sees DEBUG=false, and assumes debug mode is off. Meanwhile, the container is running with DEBUG=true because of the stray flag in the launch command. Editing or redeploying production.env won't fix the issue until that -e DEBUG=true flag is removed from the run command—and remember, Docker does not reload environment variables into existing containers; you have to recreate the container for changes to take effect.
Checking What the Container Actually Received
Before digging into application code, verify the container's runtime environment directly:
# Check a single variable docker exec webapp printenv DEBUG # List all environment variables configured on the container docker inspect webapp --format '{{range .Config.Env}}{{println .}}{{end}}' (Note: docker inspect prints secrets and tokens in plain text—avoid pasting unfiltered output into tickets or shared logs.)
Practical Guidelines
- Keep baseline config in files; reserve
-efor temporary overrides: Store stable configuration in.envfiles, and use-efor one-off local testing or quick log-level changes. Make sure temporary debug flags don't make it into permanent deployment scripts. - Don't treat
.envfiles as secret stores: Environment variables are easily visible viadocker inspectto anyone with Docker daemon access. Use Docker Secrets or a dedicated secrets manager for database passwords, tokens, and API keys. - Verify resolved configs before debugging: When Compose configurations get layered, run
docker compose configto inspect the final merged environment before starting your containers.

