How to Override Docker Compose File: Syntax and Examples

You can override a Docker Compose file by specifying multiple files with the -f option in the docker-compose command. The later files override or add to the settings in the earlier files, allowing you to customize or extend your configuration easily.

Syntax

Use the -f option multiple times or list multiple files separated by spaces to override Docker Compose settings. The order matters: files listed later override or extend the previous ones.

• docker-compose -f base.yml -f override.yml up: runs with override.yml settings overriding base.yml.
• docker-compose -f base.yml -f override.yml -f extra.yml up: applies overrides in order.

bash

docker-compose -f base.yml -f override.yml up

Example

This example shows a base Docker Compose file and an override file that changes the service's environment variable and adds a volume.

yaml

version: '3.8'
services:
  web:
    image: nginx:alpine
    environment:
      - MODE=production
    ports:
      - "80:80"

---

version: '3.8'
services:
  web:
    environment:
      - MODE=development
    volumes:
      - ./code:/usr/share/nginx/html

How to Run the Example

Save the first part as docker-compose.yml and the second part as docker-compose.override.yml. Then run:

docker-compose -f docker-compose.yml -f docker-compose.override.yml up

This command starts the web service with the environment variable MODE=development and mounts the ./code folder inside the container, overriding the base file.

bash

docker-compose -f docker-compose.yml -f docker-compose.override.yml up

Output

Starting web ... done
Attaching to web
web    | /docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
web    | /docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
web    | /docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
web    | 10-listen-on-ipv6-by-default.sh: Getting the checksum of /etc/nginx/conf.d/default.conf
web    | 10-listen-on-ipv6-by-default.sh: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
web    | /docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
web    | /docker-entrypoint.sh: Configuration complete; ready for start up

Common Pitfalls

• Order matters: The last file overrides previous ones, so list files carefully.
• Keys merge, not replace: For example, environment variables merge, but if you want to remove a variable, you must override it explicitly.
• File format: All files must be valid Compose files with compatible versions.

yaml

Incorrect override example:

# base.yml
services:
  app:
    environment:
      - VAR1=value1

# override.yml
services:
  app:
    environment:
      - VAR2=value2

# Running with both files merges environment variables, not replaces.

Correct override example:

# override.yml
services:
  app:
    environment:
      VAR1: ""
      VAR2: value2

# This clears VAR1 and sets VAR2.

Quick Reference

Tips for overriding Docker Compose files:

• Use -f option multiple times to specify files.
• Later files override or add to earlier files.
• Use docker-compose.override.yml automatically if present.
• Check merged keys carefully, especially for lists and environment variables.

Key Takeaways

Use multiple -f options to override Docker Compose files in order.

Later files override or extend settings from earlier files.

Docker Compose automatically uses docker-compose.override.yml if present.

Be careful with merging keys like environment variables; they merge, not replace by default.

Always validate your Compose files for compatibility and syntax.