Pass environment variables to Docker containers

Pass runtime settings with docker run -e, --env-file, or Compose's environment and env_file fields. Environment variables are convenient for many settings, but mounted configuration and secret files are also valid choices.

Set individual values

docker run -d --name app \
  -e DB_HOST=postgres \
  -e DB_PORT=5432 \
  -e DEBUG=false \
  -e 'MESSAGE=hello world' \
  myapp:1.2

These values are strings. The application decides what false means. Shell quoting keeps spaces or shell metacharacters within one argument.

If a variable already exists in the Docker client's exported environment, pass its name without a value:

# API_TOKEN has already been supplied securely to this shell.
docker run -d -e API_TOKEN myapp:1.2

The value comes from the CLI process's environment, which may be on a different machine from the daemon. Avoid placing real tokens directly in shell history.

Use an environment file

A simple app.env:

DB_HOST=postgres
DB_PORT=5432
DEBUG=false
MESSAGE=hello world

docker run -d --name app-from-file --env-file app.env myapp:1.2

Docker CLI environment files are not shell scripts: do not assume shell expansion, export, or shell-style quote removal. For example, quotes around a value can become literal characters. Compose's environment-file parsing has different quoting and interpolation rules. Test the format with a harmless value before moving between the two tools.

Configure Compose

services:
  app:
    image: myapp:1.2
    env_file:
      - app.env
    environment:
      DB_HOST: postgres
      DEBUG: "false"

Here, explicit environment entries override values from env_file. A Compose project's .env file primarily supplies values for interpolation in the Compose model; its mere presence does not inject every variable into a container. Reference a variable in environment or explicitly select an env_file when injection is intended.

Inspect and apply changes

Check selected nonsecret values instead of dumping the whole environment:

docker exec app printenv DB_HOST DB_PORT

The image must contain printenv. Users with sufficient Docker access can inspect the configured environment, so environment variables are not a secret vault. Keep files containing secrets out of version control, restrict access, and use a suitable secret delivery mechanism. Do not bake credentials into Dockerfile ENV instructions or image layers.

Changing an environment file does not rewrite an existing container's configuration. Recreate it with the updated settings; for Compose, run docker compose up -d app after editing the relevant configuration. A plain restart retains the old container environment.

FAQ

Can a running process change its environment? A process can change its own environment and pass values to children. That does not update unrelated processes or Docker's stored container configuration. docker exec -e DEBUG=true ... affects that new exec process and its descendants only.

Why does a cron job miss a variable? Cron may construct a separate job environment. This is not a rule that Docker variables exist only for PID 1. Pass the necessary settings explicitly using the cron implementation's supported format or a data file read by the job; never source an unescaped printenv dump.

See Docker run reference, Compose service configuration, Docker exec reference.