Multiple Compose files (override) in Docker - Commands & Configuration

Introduction

Sometimes you want to change or add settings to your Docker setup without changing the original file. Using multiple Compose files lets you keep your base setup and add or override parts easily.

When you want to add extra services only for development without changing production setup

When you need to change environment variables for testing without editing the main file

When you want to increase resource limits temporarily without touching the base config

When you want to add debugging tools to your containers only in certain cases

When you want to keep your main Compose file clean and add optional features separately

Config File - docker-compose.override.yml

docker-compose.override.yml

version: '3.8'
services:
  web:
    environment:
      - DEBUG=true
    ports:
      - "8081:80"

This file overrides the web service from the main docker-compose.yml.

It sets an environment variable DEBUG=true and changes the port mapping to 8081:80.

Docker Compose automatically uses this override file along with the main file when you run commands.

Commands

Starts the containers using both the main and override Compose files. The override settings will apply on top of the base configuration.

Terminal

docker-compose up -d

Expected Output

Creating network "example_default" with the default driver

Creating volume "example_data" with default driver

Creating example_web_1 ... done

→

-d - Run containers in the background (detached mode)

Shows the running containers and their status to verify that the services started correctly.

Terminal

docker-compose ps

Expected Output

    Name                  Command               State           Ports         

----------------------------------------------------------------------------

example_web_1   nginx -g 'daemon off;'        Up      0.0.0.0:8081->80/tcp

Displays the combined configuration from the main and override files so you can see the final settings Docker Compose will use.

Terminal

docker-compose config

Expected Output

services:

  web:

    environment:

      - DEBUG=true

    image: nginx:latest

    ports:

      - 8081:80

version: '3.8'

Key Concept

If you remember nothing else from this pattern, remember: Docker Compose automatically merges multiple files, letting you override or add settings without changing the original file.

Common Mistakes

Editing the main docker-compose.yml file directly for temporary changes

This makes it hard to keep track of changes and can cause conflicts when switching environments.

Use a separate override file to add or change settings temporarily or for specific environments.

Not using the -f flag when you want to use custom override files

Docker Compose only automatically uses docker-compose.override.yml by default; other files need to be specified explicitly.

Use 'docker-compose -f docker-compose.yml -f custom-override.yml up' to apply multiple custom files.

Summary

Use multiple Compose files to keep your base Docker setup clean and add or override settings easily.

Docker Compose automatically merges docker-compose.override.yml with the main file when you run commands.

Use 'docker-compose config' to see the final combined configuration before starting containers.