Docker Compose — Compose File Naming

2 minute read

Docker Compose supports multiple filenames, but there’s a preferred convention. This page explains the naming options and when to use each one.

Supported Filenames

Compose looks for files in this order:

Priority Filename Status
1 compose.yml ✅ Preferred (modern)
2 compose.yaml ✅ Supported
3 docker-compose.yml ⚠️ Legacy (still works)
4 docker-compose.yaml ⚠️ Legacy (still works)

Which One to Use?

Use compose.yml for all new projects.

my-project/
├── compose.yml          ← Use this
├── .env
├── Dockerfile
└── src/

The shorter name is the modern standard, endorsed by Docker’s official documentation. The docker-compose.yml name is a leftover from V1 days.

How Compose Finds the File

When you run docker compose up, Compose searches the current directory for a compose file:

Current directory: /home/user/myapp/
                                    │
  Compose looks for (in order):     │
  1. compose.yml                    │ ← Found? Use it.
  2. compose.yaml                   │ ← Found? Use it.
  3. docker-compose.yml             │ ← Found? Use it.
  4. docker-compose.yaml            │ ← Found? Use it.
  5. None found → Error             │

If multiple files exist, Compose uses the first one found in the priority order above.

Specifying a Custom File

Use -f to specify a different filename or path:

# Use a specific file
docker compose -f custom-compose.yml up -d

# Use a file in a different directory
docker compose -f /opt/stacks/web/compose.yml up -d

# Use multiple files (merged in order)
docker compose -f compose.yml -f compose.prod.yml up -d

Override Files

Compose automatically loads override files:

Main File Auto-loaded Override
compose.yml compose.override.yml
docker-compose.yml docker-compose.override.yml 
my-project/
├── compose.yml              ← Base configuration
├── compose.override.yml     ← Dev overrides (auto-loaded)
└── compose.prod.yml         ← Production (loaded with -f)

The override file is merged on top of the base file. This is great for development-specific settings:

# compose.yml — base
services:
  app:
    image: myapp:latest
    ports:
      - "3000:3000"

# compose.override.yml — dev overrides (auto-loaded)
services:
  app:
    build: .
    volumes:
      - .:/app
    environment:
      DEBUG: "true"

When you run docker compose up, both files are merged automatically.

The .yml vs .yaml Debate

Both extensions are valid YAML. The community is split:

Extension Convention
.yml Docker convention, more common in Docker/Compose
.yaml YAML specification’s preferred extension

For Compose files, use .yml — it matches Docker’s documentation and community convention.

Summary

Item Recommendation
New projects Use compose.yml
Existing projects docker-compose.yml still works
Extension .yml (Docker convention)
Override file compose.override.yml (auto-loaded)
Custom file docker compose -f myfile.yml up

Quick Reference

Item Detail
Preferred filename compose.yml
Legacy filename docker-compose.yml (still works)
Override file compose.override.yml (auto-loaded)
Custom file docker compose -f custom.yml up
Extension .yml (Docker convention)
Search order compose.yml → compose.yaml → docker-compose.yml → docker-compose.yaml

You may also enjoy