Docker Compose — Env File Directive

1 minute read

The env_file: directive loads environment variables into the container from one or more files.

Basic Usage

.env.api:

NODE_ENV=production
PORT=3000
DATABASE_URL=postgres://user:pass@db:5432/mydb

compose.yml:

services:
  api:
    image: node:20-alpine
    env_file:
      - .env.api

Multiple Files

services:
  api:
    image: node:20-alpine
    env_file:
      - .env.common
      - .env.api
      - .env.secrets

Files are loaded in order. Later files override earlier ones.

File Format Rules

# Comments start with #
NODE_ENV=production
PORT=3000
# Quotes are optional but recommended for special characters
DATABASE_URL="postgres://user:pass@db:5432/mydb"

# Empty lines are ignored

# NO spaces around = sign
# BAD: NODE_ENV = production
# GOOD: NODE_ENV=production

env_file vs environment

services:
  api:
    image: node:20-alpine
    env_file:
      - .env.api          # Loaded first
    environment:
      NODE_ENV: staging    # Overrides env_file value

Priority order (highest wins):

Priority Source
1 (highest) environment: in compose.yml
2 Host shell variables (pass-through)
3 env_file: values
4 Dockerfile ENV defaults

Optional Env Files

Use required: false (Compose v2.24+) to make a file optional:

services:
  api:
    env_file:
      - path: .env.api
        required: true
      - path: .env.local
        required: false    # Won't fail if missing

Best Practice: Separate Files per Environment

.env.common      # Shared across all environments
.env.development # Dev-specific
.env.staging     # Staging-specific
.env.production  # Prod-specific (in .gitignore!)

Summary

Feature Detail
Load from file env_file: [.env.api]
Multiple files Listed in order, last wins
Format KEY=value, one per line
Override by environment: key wins
Optional files required: false (v2.24+)

Quick Reference

Item Detail
env_file: Load vars from file into container
Format KEY=value, # for comments
Order Later files override earlier
Override environment: always wins over env_file
Optional required: false (Compose v2.24+)

You may also enjoy