Docker Compose env_file vs ${VAR}: Fix Interpolation

Why env_file does not fill ${VAR}#

Consider this file:

1
services:
2
  web:
3
    env_file:
4
      - ./runtime.env
5
    image: "my-web:${IMAGE_TAG}"

runtime.env can populate the environment inside the web container, but Compose must resolve image while it is constructing the model. If IMAGE_TAG is not available from the interpolation sources, the image can become my-web: or produce an unset-variable warning.

This is why changing a service’s env_file can appear to do nothing for an image tag, volume path, port, or build argument. Those fields were already parsed before the container environment existed.

Use the right source for interpolation#

1
IMAGE_TAG=2026.08

1
services:
2
  web:
3
    image: "my-web:${IMAGE_TAG}"

1
IMAGE_TAG=2026.08-rc1
2
PUBLIC_ORIGIN=https://staging.example.com

1
docker compose --env-file ./config/.env.dev config
2
docker compose --env-file ./config/.env.dev up -d

1
IMAGE_TAG=2026.08 docker compose --env-file ./config/.env.dev config

Fail early when a value must exist#

An empty substitution can survive parsing and fail later as an invalid image, URL, or host path. Use the required-value form when a default would be unsafe:

1
services:
2
  web:
3
    image: "my-web:${IMAGE_TAG:?Set IMAGE_TAG before starting Compose}"
4
    environment:
5
      PUBLIC_ORIGIN: "${PUBLIC_ORIGIN:?Set PUBLIC_ORIGIN before starting Compose}"

Use a default only when the default is a valid and intentional environment:

1
services:
2
  web:
3
    environment:
4
      LOG_LEVEL: "${LOG_LEVEL:-info}"

The distinction between ${VAR:-default} and ${VAR?error} matters: the former treats an empty value as missing, while the latter checks whether the variable is set. Choose the form that matches the deployment contract.

Keep container environment and model interpolation separate#

A service can use both mechanisms, but each has a different job:

1
services:
2
  web:
3
    image: "my-web:${IMAGE_TAG:?Set IMAGE_TAG}"
4
    env_file:
5
      - ./runtime.env
6
    environment:
7
      PUBLIC_ORIGIN: "${PUBLIC_ORIGIN:?Set PUBLIC_ORIGIN}"

Here IMAGE_TAG and PUBLIC_ORIGIN must be available while Compose parses the file. runtime.env can provide additional values to the running container. If the same key appears in several sources, check the documented precedence for the specific field instead of treating every environment file as interchangeable.

For a modular Compose project, the include path and env_file guide covers how an included file gets its own project directory and interpolation inputs. This article is narrower: it explains why a service-level environment file cannot retroactively fill a ${VAR} in the Compose model.

Verify the same model CI will run#

Use a safe, non-secret configuration check in CI:

1
set -euo pipefail
2

3
docker compose --env-file ./config/.env.ci config --environment
4
docker compose --env-file ./config/.env.ci config >/tmp/compose.resolved.yaml
5
rg 'image:|PUBLIC_ORIGIN:|LOG_LEVEL:' /tmp/compose.resolved.yaml

Do not dump the full resolved file when it contains passwords, tokens, or connection strings. A better pipeline prints the image reference and a boolean for each required variable, then starts the service only after config succeeds.

Docker documents .env interpolation as a Compose CLI feature. If the same YAML is passed to docker stack deploy, do not assume the Swarm command supports the same substitution behavior; test that deployment path separately.

Takeaway#

Use --env-file, project .env, or the shell to resolve ${VAR}; use service env_file for the container’s runtime environment. Run docker compose config --environment and docker compose config before up so a missing value fails at the parsing boundary.

FAQ#