Docker Compose Environment Variables and .env Files

DevOps engineer configuring Docker Compose environment variables and env files on a laptop in a datacenter

To configure docker compose environment variables, you can define variables directly under the environment attribute in your compose.yaml, load external files using the env_file directive, or rely on a project-root .env file for variable interpolation. Understanding how Docker Compose evaluates these sources is essential for managing database credentials, API endpoints, and dynamic port bindings securely across development and production environments. This guide explains the core methods for passing environment variables to containers, clarifies precedence rules, and provides real-world patterns to prevent configuration errors.

Managing configuration outside of container images follows twelve-factor application methodology. When running multi-container stacks—whether deploying monitoring dashboards or managing container runtimes as outlined in our guide on Podman vs Docker—hardcoding connection strings into compose definitions introduces severe operational risks. For enterprise workloads requiring automated rotation and encryption, adopting dedicated tooling like Infisical for Docker Compose is recommended. For standard deployments, mastering native Compose environment handling gives you complete control over your services.

Prerequisites

Before proceeding, verify that your environment satisfies these baseline requirements:

  • Docker Engine and Compose v2: Docker Compose is integrated into the Docker CLI. Verify your setup with docker compose version.
  • Terminal access: Basic familiarity with Linux terminal commands and YAML syntax.
  • A clean workspace: Create a test directory such as ~/compose-env-demo.

Method 1: Direct Definition with the environment Attribute

The most explicit way to provide variables to a container is through the environment attribute inside compose.yaml. Docker Compose injects these key-value pairs directly into the container’s runtime process.

Mapping Syntax

Mapping syntax uses standard YAML key-value pairs and is recommended for readability:

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    environment:
      APP_ENV: production
      LOG_LEVEL: info

Sequence Syntax and Host Pass-Through

Sequence syntax uses a list of strings formatted as KEY=VALUE. You can also pass host environment variables through without defining a value:

services:
  web:
    image: nginx:alpine
    environment:
      - APP_ENV=production
      - HOST_HOSTNAME
      - SECRET_TOKEN

If HOST_HOSTNAME is exported in your terminal (export HOST_HOSTNAME="node-01"), Compose forwards its value into the container. If unset on the host, Compose passes an empty string.

Method 2: Injecting Variables Using the env_file Attribute

Listing dozens of variables in compose.yaml creates cluttered files and risks committing sensitive values to Git. The env_file attribute tells Compose to load external files directly into the container process.

Setting Up an External Environment File

Create a dedicated file named api.env:

# Database configuration
DB_HOST=postgres-db
DB_PORT=5432
DB_USER=app_user
DB_PASSWORD=SuperSecretPassword123!
DEBUG_MODE=false

Referencing env_file in compose.yaml

Reference the external file inside your service definition:

services:
  api:
    image: python:3.11-slim
    env_file:
      - api.env
    environment:
      DEBUG_MODE: "true"

Values declared under environment take precedence over values loaded from env_file, allowing you to set defaults in an env file and selectively override them.

Using Multiple Environment Files

You can specify multiple files in env_file. Compose processes them sequentially from top to bottom; if keys collide, the last file wins:

services:
  worker:
    image: redis:7-alpine
    env_file:
      - base.env
      - production.env

Method 3: Variable Interpolation Using the Project-Root .env File

A frequent point of confusion is the difference between injecting variables into a container and interpolating variables into compose.yaml itself.

Docker Compose automatically reads a file named .env in the same directory as compose.yaml. Variables in this root .env are not passed into containers by default. Instead, Compose uses them for string substitution across your Compose file.

Defining Project Interpolation in .env

Create a root .env file:

PROJECT_PORT=8000
IMAGE_TAG=1.26-alpine
DATA_PATH=/opt/app/data

Using Interpolated Variables in compose.yaml

Reference these variables in compose.yaml using ${VARIABLE} syntax:

services:
  web:
    image: nginx:${IMAGE_TAG}
    ports:
      - "${PROJECT_PORT}:80"
    volumes:
      - ${DATA_PATH}/html:/usr/share/nginx/html:ro

When running docker compose up, Compose resolves ${IMAGE_TAG} to 1.26-alpine and ${PROJECT_PORT} to 8000 before creating resources.

Advanced Substitution Syntax

Compose supports standard parameter expansion rules for dynamic values:

  • Default fallback (${VAR:-default}): Uses default if VAR is unset or empty (e.g., image: redis:${REDIS_TAG:-alpine}).
  • Default if unset only (${VAR-default}): Uses default only if VAR is completely unset; keeps empty strings.
  • Mandatory check (${VAR:?error}): Exits with an error if VAR is unset or empty (e.g., DB_PASSWORD: "${DB_SECRET:?Database password required}").
  • Literal dollar signs ($$): Escape literal dollar signs in strings, regex, or script blocks with $$.

Method 4: CLI Flags and Host Shell Overrides

In CI/CD pipelines, you frequently need to switch environments without editing configuration files on disk.

Using the –env-file Flag

To use an alternative interpolation file instead of the default root .env, pass --env-file:

docker compose --env-file .env.production up -d

Runtime Overrides with docker compose run -e

To temporarily override an environment variable for a one-off command, pass -e:

docker compose run -e DEBUG_MODE=true web python manage.py migrate

Environment Variable Precedence in Docker Compose

When a variable is defined in multiple locations, Docker Compose evaluates it based on a strict hierarchy from highest (overrides all) to lowest:

Precedence Level Source Mechanism Target Scope Description
1 (Highest) CLI flags (docker compose run -e) Container process Runtime command-line overrides.
2 Host shell environment Container & Interpolation Exported terminal shell variables.
3 environment block in compose.yaml Container process Explicit mappings declared on the service.
4 Custom file via --env-file flag Compose interpolation Alternative file passed to the CLI for template substitution.
5 env_file block in compose.yaml Container process External key-value files loaded into the container.
6 Project-root .env file Compose interpolation Default file for resolving ${VAR} placeholders in YAML.
7 (Lowest) Dockerfile ENV instructions Container process Default values baked into the container image.

How to Verify Resolved Variables

Always verify your configuration before running containers in production.

Inspect Substituted Compose Configuration

To view the resolved YAML with all variables interpolated without starting containers, run:

docker compose config

Inspect the output to confirm that image tags, volume paths, and environment blocks match expectations.

Inspect Runtime Container Variables

To inspect variables inside a running container, execute:

docker compose exec web env

This confirms exactly which environment variables are exposed to your application process.

Common Mistakes and How to Avoid Them

1. Expecting Root .env Variables to Exist Inside the Container

Problem: Defining API_KEY=xyz in .env does not automatically make it available inside the container application.

Cause: The root .env file only resolves placeholders in compose.yaml.

Fix: Explicitly pass the variable under the environment attribute:

services:
  app:
    image: my-app:latest
    environment:
      API_KEY: ${API_KEY}

2. Unescaped Dollar Signs in Passwords

Problem: Setting DB_PASSWORD="p@$$word123" causes Compose to treat $$word123 as a variable name and truncate it.

Cause: Compose interprets single dollar signs as variable substitutions.

Fix: Escape dollar signs by doubling them ($$) in compose.yaml: DB_PASSWORD: "p@$$$$word123".

3. Formatting Issues with Inline Comments and Spaces

Problem: Adding inline comments like PORT=8080 # http port causes Compose to include # http port in the value.

Fix: Place comments on dedicated lines starting with #. If a value contains spaces, wrap it in double quotes (NAME="My App").

Frequently Asked Questions

What is the difference between a docker compose env file and the project .env file?

A project-root .env file is used by Docker Compose for variable substitution inside compose.yaml (such as dynamic ports or image tags). An external environment file referenced via the env_file attribute is parsed and passed directly into the container process runtime without modifying the Compose template.

How do I provide a default fallback value if an environment variable is unset?

Use bash parameter expansion syntax: ${VARIABLE:-default_value} in compose.yaml. If VARIABLE is empty or undeclared, Docker Compose uses the fallback value. For example, image: redis:${REDIS_TAG:-7-alpine} defaults to version 7-alpine.

Can I use multiple env files in a single Docker Compose service?

Yes. The env_file attribute accepts an array of file paths. Files are evaluated in order from top to bottom. If the same variable key exists in multiple files, the value from the last file in the list takes precedence.

Conclusion

Configuring Docker Compose environment variables properly ensures clean separation between application code and operational configuration. Use the environment attribute for service-specific definitions, env_file for bulk settings, and the project-root .env file for template interpolation. Always test your configuration using docker compose config before deploying to keep multi-container deployments reliable and reproducible.