Docker Compose — Override Files

1 minute read

Docker Compose automatically loads compose.override.yml to merge development-specific settings on top of your base compose file.

How Override Works

compose.yml              ← Base configuration (committed)
  +
compose.override.yml     ← Dev overrides (auto-loaded)
  =
Resolved configuration   ← What Compose actually uses

Example

compose.yml (base — production-like):

services:
  api:
    image: myapi:latest
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production

  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

compose.override.yml (development overrides):

services:
  api:
    build: ./api                    # Build locally instead of pull
    volumes:
      - ./api:/app                  # Mount source code
    command: npm run dev            # Dev server with hot reload
    environment:
      NODE_ENV: development         # Override environment
      DEBUG: "*"
    ports:
      - "9229:9229"                 # Add debug port

Merge Rules

Element Behavior
Scalar values Override replaces base
Maps (environment) Merged (override wins on conflict)
Lists (ports) Appended
volumes Appended 
docker compose config    # View the merged result

.gitignore Patterns

# Committed
compose.yml

# Git-ignored (developer-specific)
compose.override.yml

Or the reverse:

# Committed
compose.yml
compose.override.yml     # Dev config shared with team

# Git-ignored
compose.local.yml        # Personal overrides

Skip Override

To explicitly skip the override file:

docker compose -f compose.yml up -d

The auto-loading only happens when you don’t specify -f.

Named Override Files

For production, use a separate named file:

docker compose -f compose.yml -f compose.prod.yml up -d

compose.prod.yml:

services:
  api:
    image: ghcr.io/myorg/api:v1.2.3
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

Summary

File Auto-loaded Purpose
compose.yml Yes Base configuration
compose.override.yml Yes Dev overrides
compose.prod.yml No (-f flag) Production
compose.test.yml No (-f flag) Testing

Quick Reference

Item Detail
compose.override.yml Auto-loaded for dev overrides
Merge Scalars replaced, maps merged, lists appended
Skip Use -f compose.yml explicitly
Production -f compose.yml -f compose.prod.yml
Verify docker compose config

You may also enjoy