DEV Community

Frank Zhang
Frank Zhang

Posted on

Docker --env-file vs. -e: Which One Wins?

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
Enter fullscreen mode Exit fullscreen mode

And you start a container with:

docker run --rm \
  --env-file app.env \
  -e APP_MODE=production \
  alpine printenv APP_MODE
Enter fullscreen mode Exit fullscreen mode

Docker outputs:

production
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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'
Enter fullscreen mode Exit fullscreen mode

Output:

production
warning
8080
Enter fullscreen mode Exit fullscreen mode
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 -e flags: -e APP_MODE=production assigns an explicit value, whereas -e APP_MODE (with no =) tells Docker to pull the variable from your host shell. If APP_MODE isn'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"]
Enter fullscreen mode Exit fullscreen 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:

  1. .env vs. env_file: A project-level .env file in your working directory is used for variable interpolation inside compose.yml (such as APP_MODE: ${APP_MODE}). Unlike env_file, it does not automatically inject all of its variables into your containers.
  2. Interpolation: Compose supports ${VAR} variable interpolation inside files loaded via env_file. Plain docker run --env-file does 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
Enter fullscreen mode Exit fullscreen mode

Inside production.env, everything looks right:

APP_MODE=production
DEBUG=false
LOG_LEVEL=warning
Enter fullscreen mode Exit fullscreen mode

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}}'
Enter fullscreen mode Exit fullscreen mode

(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 -e for temporary overrides: Store stable configuration in .env files, and use -e for 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 .env files as secret stores: Environment variables are easily visible via docker inspect to 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 config to inspect the final merged environment before starting your containers.

Top comments (0)