How to override Docker Compose settings?

· Category: Docker

Short answer

Docker Compose automatically reads docker-compose.override.yml to apply local overrides. You can also specify multiple files with -f to layer configurations for different environments.

Steps

  1. Create docker-compose.override.yml in the same directory.
  2. Define only the keys you want to override.
  3. Run docker compose up as usual; overrides are merged automatically.

Example

# docker-compose.yml
services:
  web:
    image: myapp
    ports:
      - "80:80"

# docker-compose.override.yml
services:
  web:
    ports:
      - "8080:80"
    volumes:
      - ./src:/app/src

Start with a specific file:

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

Tips

  • Use docker compose config to view the merged configuration.
  • Keep the base file minimal and environment-specific settings in override files.
  • Override files are ignored when explicit -f flags are used.

Common issues

  • YAML merging replaces entire arrays rather than appending; be careful with lists.
  • Relative paths in override files are resolved from the override file location.
  • Environment variables are merged, but explicit values in overrides take precedence.