Docker Compose: Define and Run Multi-Container Apps

What Docker Compose is

Docker Compose is the tool for defining and running multi-container applications on Docker. Instead of starting a web server, a database, a cache and a queue by hand with a series of docker run commands, you describe every service in one YAML file and bring the whole stack up with a single command, docker compose up. The file follows the Compose Specification, an open format for describing multi-container applications, and the docker/compose repository is Docker's implementation of that specification.

The Docker documentation positions Compose as useful in every environment: local development, staging, testing and CI workflows, and single-host production. Beyond starting and stopping a stack, the CLI covers the application lifecycle: rebuilding services, showing their status, streaming logs and running one-off commands inside a service.

The audience is broad. Application developers use it to spin up the dependencies their code needs, platform and QA teams use it to create disposable test environments, and small teams use it to run self-hosted services on a single server.

How Compose works

Compose works from an application model defined in the Compose file. The docs describe the main building blocks:

• Services: the computing components of the application, each implemented by running the same container image and configuration one or more times.
• Networks: the IP routes that let containers in connected services talk to each other.
• Volumes: persistent data that services store and share, described as high-level filesystem mounts.
• Configs: runtime or platform-dependent configuration that is mounted into containers as files.
• Secrets: a flavour of config for sensitive data, also exposed to services as mounted files.
• Projects: an individual deployment of the specification. The project name groups resources together, so the same Compose file can be deployed twice on one host under different names.

The default file is compose.yaml (preferred) or compose.yml in the working directory; docker-compose.yaml and docker-compose.yml are still accepted for backwards compatibility. Several Compose files can be merged: simple attributes and maps are overridden by later files, while lists are appended. An include element lets one application reuse a Compose file owned by another team.

The CLI is invoked as docker compose, a Docker CLI plugin. According to the history page in the Docker docs, Compose v1 was a Python tool invoked as docker-compose; Compose v2, announced in 2020, was rewritten in Go and ignores the old top-level version key. Compose v5, released in 2025, is described as functionally identical to v2, with the main addition being an official Go SDK. The version number jumped to 5 to avoid confusion with the legacy "v2" and "v3" file formats. The Python implementation is still available on the repository's v1 branch.

Key features

• Single-file application definition: services, networks, volumes, configs and secrets live in one YAML file that can be committed with the code.
• One command lifecycle: up, down, ps, logs, exec and build operate on the whole stack or on a single service.
• Container reuse: Compose caches the configuration used to create a container; when you restart a service that has not changed, it reuses the existing container, which the docs say makes iteration fast.
• Variables and .env files: Compose reads a .env file automatically and supports interpolation in the Compose file, so one definition can be adapted per environment or per developer.
• Compose Watch: a develop.watch block defines rules such as sync+restart or rebuild, so file changes on the host are synced into running containers or trigger an image rebuild. Watch rules can ignore paths like node_modules/, and .git directories are ignored automatically.
• Multiple files and includes: an override file such as compose.production.yaml can be layered on the base file with -f.
• Config preview: docker compose config renders the resolved configuration without starting the stack.
• Go SDK: since v5, the docker/compose package can be used as a Go library to load, validate and manage Compose projects without shelling out to the CLI.

Getting started with Docker Compose

On Windows and macOS, the README notes that Compose is included in Docker Desktop. On Linux with Docker Engine already installed, the Docker docs describe installing the plugin from Docker's package repository. For Ubuntu and Debian:

sudo apt-get update
sudo apt-get install docker-compose-plugin

Then check the installation:

docker compose version

The README also documents a manual route: download a binary from the GitHub releases page, rename it to docker-compose and copy it to $HOME/.docker/cli-plugins (or a system-wide CLI plugins folder).

A minimal Compose file from the README defines a web service built from the local Dockerfile and a Redis service from a public image:

services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - .:/code
  redis:
    image: redis

The day-to-day commands documented in the "How Compose works" guide are:

docker compose up
docker compose down
docker compose logs
docker compose ps

For a development loop with file syncing, the quickstart starts the stack with Watch enabled:

docker compose up --watch

Use cases

• Local development environments: the docs describe documenting every service dependency (databases, queues, caches, web APIs) in the Compose file so a multi-page "getting started" guide becomes one machine-readable file and a few commands.
• Automated testing: CI jobs can create an isolated environment, run the suite and tear it down again. The docs show the pattern as docker compose up -d, a test script, then docker compose down.
• Single-host deployments: Compose supports production deployments on one server, typically with a production override file, restart policies and no bind-mounted source code. Redeploying one service is docker compose build web followed by docker compose up --no-deps -d web.
• Remote Docker hosts: setting DOCKER_HOST, DOCKER_TLS_VERIFY and DOCKER_CERT_PATH points the normal commands at another machine.
• Embedding orchestration in tools: the Go SDK lets deployment pipelines or internal tools load and start Compose projects programmatically.

How Docker Compose compares

Compose sits between running individual containers with docker run and running a cluster orchestrator. Its focus is a whole application on one Docker host; the production guide says that to scale up you can run Compose apps on a Swarm cluster, and the Docker docs list Compose Bridge as a way to transform a Compose configuration into configuration files for other platforms, such as Kubernetes.

The README calls out Docker Swarm specifically: Swarm relied on the legacy Compose file format and did not adopt the Compose Specification, so it misses recent syntax enhancements. After Swarm's acquisition by Mirantis, the README says it is no longer maintained by Docker Inc., and some Compose features are not available to Swarm users.

Things to know before adopting Docker Compose

• License: Apache-2.0. On Windows and macOS the usual way to get Compose is through Docker Desktop, which bundles it with Docker Engine and the Docker CLI.
• Install method matters on Linux: the docs recommend Docker Desktop or the repository-based plugin. Manual plugin installs do not auto-update, and the standalone docker-compose install is described as legacy, kept for backward compatibility.
• Old files may need edits: files written in Compose file format 1, which lacks a top-level services key, do not run with Compose v2 or v5. The version key is ignored.
• Watch has requirements: Watch only tracks services built from local source via build, not pre-built images, and the container image needs stat, mkdir and rmdir, with the container user able to write to the target path.
• Data lives in volumes: the quickstart notes that docker compose down removes containers and anything written to their writable layer; use named volumes for state, and remember down -v removes those too.
• Go SDK pinning: the SDK docs say Compose v5 currently depends on github.com/docker/docker, so projects need to pin docker/cli v28.5.2+incompatible to avoid build errors.

Project activity

As of October 2026 the repository has about 38,400 stars. It was created in December 2013, is written in Go and is licensed under Apache-2.0, with commits landing in October 2026. The main module path is github.com/docker/compose/v5. The source and releases are at github.com/docker/compose, and the user documentation is at docs.docker.com/compose. Issues are reported on the GitHub issue tracker, and contributions follow the repository's CONTRIBUTING.md.