Override Files & Merging

Layering Compose Files

Multiple -f flags merge in order; later files add to or override earlier ones:

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

You can even skip -f: if both compose.yaml and compose.override.yaml exist in the directory, Compose combines them automatically — the base stays the developer default and the override is often git-ignored per machine. Override files do not need to be complete Compose files; a fragment containing just services.web.ports is valid, because only the merged model must be complete.

Merge Rules

The rules follow YAML shape:

One sharp edge: command, entrypoint, and healthcheck.test are overridden wholesale, not appended. And because ports concatenate, declaring the same port in base and override yields two entries — use !override to replace the whole list instead.

Paths, Reset, and Pitfalls

All relative paths — build contexts, bind mounts, env_file — resolve against the base file (the first -f, or the directory Compose found compose.yaml in). An override in another folder does not rebase them; --project-directory changes the anchor, and the top-level include element is the fix when you want each file resolved from its own location.

To delete a declaration rather than replace it, tag it with !reset:

services:
  web:
    volumes: !reset []

!override forces full replacement where normal merge would append. Interview: pick -f layering for CI vs include for shared team files, and explain how docker compose config proves the merge before you up.