Docker Compose v3 Developer Reference [2026 Cheat Sheet]

What v3 Means in 2026

Keep the mental model simple: the modern command is docker compose, the modern file model is the Compose Specification, and the old top-level version: "3" line is mostly historical baggage. Docker still parses it for backward compatibility, but current validation uses the latest schema rather than freezing behavior to a numeric version.

• Use compose.yaml or compose.yml as the preferred filename.
• Prefer docker compose over docker-compose.
• Treat v3 as a legacy label, not a target runtime mode.
• Use docker compose config to see what Docker will actually run after merges, interpolation, and defaults.

Quick Command Reference

Breadth first: these are the commands most teams actually need, grouped by purpose instead of alphabetically. The authoritative CLI reference is Docker’s Compose command index.

Start, build, and bootstrap

• docker compose up: create and start services.
• docker compose up -d: detached startup.
• docker compose up --build: rebuild images before starting.
• docker compose build: build only.
• docker compose pull: fetch upstream images.
• docker compose create: create containers without starting them.

docker compose pull
docker compose build
docker compose up -d

Inspect and observe

• docker compose ps: list service containers.
• docker compose logs -f SERVICE: follow logs for one service.
• docker compose images: list images in the project.
• docker compose top: inspect running processes.
• docker compose port SERVICE CONTAINER_PORT: print a published port.
• docker compose events: stream lifecycle events.
• docker compose ls: list Compose projects on the host.
• docker compose version: print Compose version info.

docker compose ps
docker compose logs -f api
docker compose ls

Exec, run, and debug

• docker compose exec SERVICE sh: enter a running container.
• docker compose exec -T SERVICE CMD: non-TTY exec for scripts.
• docker compose run --rm SERVICE CMD: one-off disposable container.
• docker compose cp: copy files between local disk and a service container.
• docker compose attach: attach stdio to a running service.

docker compose exec api sh
docker compose exec -T db psql -U app appdb
docker compose run --rm api python manage.py migrate

Lifecycle control

• docker compose stop: graceful stop.
• docker compose start: restart previously created containers.
• docker compose restart: bounce running services.
• docker compose pause and unpause: freeze or resume processes.
• docker compose kill: hard stop.
• docker compose wait: block until containers stop.

docker compose restart worker
docker compose stop
docker compose wait

Cleanup and reset

• docker compose down: stop and remove containers and networks.
• docker compose down -v: also remove named volumes declared by the project.
• docker compose rm: remove stopped service containers only.
• docker compose down --remove-orphans: remove leftover services from prior configs.

docker compose down --remove-orphans
docker compose down -v

Global options you will actually use

• -f FILE: stack multiple Compose files.
• -p NAME: override project name.
• --profile NAME: enable optional services.
• --env-file FILE: point at a different env file.
• --dry-run: preview command effects without applying them.
• --parallel N: control concurrent operations like pulls and builds.

docker compose -f compose.yaml -f compose.dev.yaml --profile debug up --build
docker compose --env-file .env.staging config
docker compose --dry-run up

Compose Configuration

The safest 2026 baseline is a spec-style compose.yaml with no top-level version. Start with services, volumes, networks, secrets, and configs; then add profiles and develop-time watch rules as needed.

name: boring-app

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    command: npm run dev
    ports:
      - '3000:3000'
    env_file:
      - .env
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://app:app@db:5432/app
    volumes:
      - .:/workspace
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ['CMD-SHELL', 'curl -f http://localhost:3000/health || exit 1']
      interval: 10s
      timeout: 3s
      retries: 5
    profiles:
      - app

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U app -d app']
      interval: 5s
      timeout: 3s
      retries: 10

  adminer:
    image: adminer
    ports:
      - '8080:8080'
    profiles:
      - debug

volumes:
  pgdata:

Core keys worth memorizing

• services: the application graph.
• image or build: where a service comes from.
• command and entrypoint: runtime behavior overrides.
• ports: host-to-container publishing.
• volumes: bind mounts and named volumes.
• environment and env_file: container env injection.
• depends_on: startup relationships, often paired with healthcheck.
• profiles: opt-in services for dev, debug, or ops tasks.
• secrets and configs: structured runtime assets beyond raw env vars.

If you need to share snippets publicly, scrub credentials first. For redacting env samples or YAML dumps before docs or bug reports, TechBytes’ Data Masking Tool is the right fit.

For rough YAML cleanup before pasting into tickets or PRs, the Code Formatter is a useful companion.

Advanced Usage

Profiles for optional services

Profiles are the cleanest way to keep one Compose model while avoiding “always-on” auxiliary services. Put database UIs, mail catchers, seed jobs, observability sidecars, and migration runners behind a profile. Docker’s profile guide is here: Using profiles with Compose.

docker compose --profile debug up -d
docker compose run --rm db-migrations

Develop-time watch workflows

Compose Watch is one of the biggest quality-of-life improvements in the modern toolchain. Official docs describe develop.watch with sync and rebuild actions, and note that docker compose up --watch or docker compose watch can drive that flow. Source: Use Compose Watch.

services:
  web:
    build: .
    command: npm run dev
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
          initial_sync: true
          ignore:
            - node_modules/
        - action: rebuild
          path: package.json

Multiple files, merge rules, and include

Compose supports layered files through repeated -f flags, and Docker’s docs also describe include for reusing other Compose files. Use separate files when an environment truly changes behavior; use profiles when the same environment only toggles optional services.

docker compose -f compose.yaml -f compose.dev.yaml config
docker compose -f compose.yaml -f compose.prod.yaml up -d

Rule of thumb:

• Use profiles for optional services.
• Use multiple -f files for environment overrides.
• Use docker compose config after every nontrivial merge.

Validation and preview

Two commands deserve a permanent slot in your shell history. docker compose config renders the resolved model, while --dry-run previews the operational effect of a command. This is the fastest way to catch bad interpolation, path mistakes, duplicate ports, and broken overrides before a container even starts.

docker compose config
docker compose config --services
docker compose --dry-run up --build

Keyboard Shortcuts

This reference ships with lightweight page controls so you can scan it like a terminal cheat sheet instead of a long-form article.

Common Pitfalls

1. Assuming `version: "3"` changes behavior. It does not lock you onto a legacy parser in modern Compose; it mainly triggers an obsolete warning.
2. Using `depends_on` as readiness logic without `healthcheck`. Container start order is not the same thing as application readiness.
3. Mixing bind mounts and watch rules blindly. Use each intentionally; too much overlap creates confusing state.
4. Forgetting project naming. Service names, networks, and volumes are scoped by project, so -p and directory names matter.
5. Skipping `config` before `up`. Most “Compose is weird” bugs are just merge, interpolation, or path issues you could have rendered upfront.
6. Treating `docker-compose` and `docker compose` as identical forever. Modern docs and features land on the V2 CLI path first.

The official references most worth bookmarking are Compose file reference, Compose CLI reference, profiles, and watch mode.