Docker Compose override files let you maintain one base configuration with environment-specific adjustments layered on top — avoiding duplicated, drifting compose files for each environment.
The Problem This Solves
Development and production often need different settings (different environment variables, resource limits, exposed ports for debugging) — maintaining entirely separate compose files for each environment leads to duplication and drift; override files let you share a common base while cleanly layering differences.
Base Configuration
nano docker-compose.ymlservices:
app:
build: .
environment:
- NODE_ENV=production
restart: unless-stopped
db:
image: postgres:16
volumes:
- postgres-data:/var/lib/postgresql/data
volumes:
postgres-data:Development Override
nano docker-compose.override.ymlservices:
app:
build:
target: development
environment:
- NODE_ENV=development
volumes:
- ./src:/app/src
ports:
- "9229:9229"docker-compose.override.yml is automatically applied when present, without needing to specify it explicitly — ideal for a local development default.
Using the Base + Override Automatically
docker compose up -dDocker Compose automatically merges docker-compose.yml with docker-compose.override.yml if the latter exists in the same directory.
Production-Specific Override
nano docker-compose.prod.ymlservices:
app:
deploy:
resources:
limits:
memory: 1G
restart: alwaysExplicitly Combining Base + a Named Override File
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -dUnlike the automatically-applied docker-compose.override.yml, named files like docker-compose.prod.yml must be explicitly specified with -f.
How Merging Works
Override files merge with (not replace) the base configuration — specific values in the override take precedence, while unspecified settings inherit from the base; understand this merge behavior to avoid unexpected configuration combinations.
Keeping Secrets Out of Compose Files
See Docker Compose .env Files and Environment Variables Explained — combine override files (for structural differences) with .env files (for actual secret values) rather than hardcoding sensitive values directly in any compose file, including overrides.
Organizing Multiple Environment Overrides
docker-compose.yml # base
docker-compose.override.yml # local dev (auto-applied)
docker-compose.staging.yml # staging-specific
docker-compose.prod.yml # production-specificCombining with Profiles for Even More Flexibility
See How to Use Docker Compose Profiles and Multiple Environments — profiles and override files are complementary techniques; profiles control which services run, override files control how they're configured.
Common Errors
Unexpected configuration in a specific environment — use docker compose config to view the fully merged, effective configuration, helping you understand exactly what's being applied after all overrides are combined.
Continue Reading
- How to Use Docker Compose Profiles and Multiple Environments
- Docker Compose .env Files and Environment Variables Explained
- VPS Hosting for Developers: Setting Up a Dev/Staging Environment
Browse more articles in Docker & Containers.
