If you have ever run a single container with docker run and then realized your app also needs a database, a cache, and a worker, you have felt the exact pain this tool solves. So what is Docker Compose? It is a tool that defines an entire multi-container application in one YAML file and lets you start, stop, or rebuild the whole stack with a single command. In 2026 it is still the fastest way to stand up a realistic local development environment.
What changed in 2026
Compose has quietly modernized, and a few old habits will now bite you:
- Compose v2 is the only version. The original Python
docker-compose binary is retired. Everything is the Go-based plugin, so you type docker compose (with a space), not docker-compose (with a hyphen).
compose.yaml is the canonical filename. docker-compose.yml still works, but the shorter name is preferred, and the old top-level version: key is ignored — you can delete it.docker compose watch is mature. It syncs source changes into running containers or triggers a rebuild automatically, replacing hand-rolled volume-mount reload hacks.- The Compose Spec is an open standard. Other tools read the same file format, so your
compose.yaml is more portable than it used to be.
What Docker Compose actually does
A Compose file has three main building blocks. Services are your containers — one per process, like web, db, or redis. Networks connect them so services can reach each other by name. Volumes persist data so a db container does not lose everything when it restarts.
The payoff is that a teammate can clone your repo, run one command, and get the identical stack you have — same Postgres version, same environment variables, same wiring. No twelve-step README that drifts out of date.
A minimal compose.yaml
# compose.yaml
services:
web:
build: .
ports: ["3000:3000"]
environment:
DATABASE_URL: postgres://app:secret@db:5432/app
depends_on: [db, cache]
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: secret
POSTGRES_DB: app
volumes:
- pgdata:/var/lib/postgresql/data
cache:
image: redis:7-alpine
volumes:
pgdata:
Note how web reaches the database at the hostname db — Compose creates a shared network and uses each service name as its DNS name. No IP addresses to hardcode.
The commands you actually use
You can get 90% of the value from a handful of commands.
| Command |
What it does |
docker compose up -d |
Build and start the whole stack in the background |
docker compose down |
Stop and remove containers and networks |
docker compose down -v |
Same, but also delete named volumes (wipes data) |
docker compose logs -f web |
Tail the logs of one service |
docker compose exec db psql |
Open a shell or tool inside a running service |
docker compose ps |
List what is running and on which ports |
Compose vs Dockerfile vs Kubernetes
These get confused constantly, so here is the honest split:
| Tool |
Job |
Scope |
| Dockerfile |
Builds one image (the recipe) |
A single service |
| Docker Compose |
Runs several containers together |
One machine |
| Kubernetes |
Schedules containers across a cluster |
Many machines |
A Dockerfile and a Compose file are complements, not rivals: Compose usually points at your Dockerfile via build: .. Compose and Kubernetes, however, overlap — and Compose loses at production scale. Compose has no self-healing across nodes, no rolling deploys, no autoscaling. It runs on one host.
What to skip and watch out for
- Do not run Compose as your production orchestrator for anything serious. It is great for a small single-server side project, fine for CI, but if you need high availability across machines, reach for Kubernetes or a managed platform.
- Do not commit secrets in
environment:. Use an .env file that is gitignored, or Docker secrets. Passwords in a committed compose.yaml end up in your git history forever.
- Do not lean on
depends_on for readiness. It waits for a container to start, not for the database to accept connections. Add a healthcheck or a retry loop in your app.
- Do not pin to
latest. Use explicit tags like postgres:16-alpine so a rebuild next month does not silently jump a major version. Verify current stable tags yourself before pinning.
FAQ
Is Docker Compose free?
Yes — the Compose plugin is open source. Docker Desktop, which bundles it on Mac and Windows, requires a paid subscription for larger businesses, but the underlying CLI and engine on Linux are free. Check Docker current licensing terms before rolling it out at work.
What is the difference between docker-compose and docker compose?
The hyphenated docker-compose is the old Python v1 tool, now removed. The spaced docker compose is the current Go plugin. Use the spaced form in 2026.
Can I use Compose in production?
For a single small server, yes, and plenty of people do. For multi-machine, high-availability workloads, no — that is what orchestrators like Kubernetes exist for.
Do I still need a Dockerfile if I use Compose?
Usually yes. Compose orchestrates images; a Dockerfile builds your custom image. You only skip the Dockerfile when every service uses a prebuilt public image.
Where to go next
Compose is one piece of a modern workflow. Once your stack runs locally, automate testing and deploys with what is CI/CD, design the API your web service exposes with what is GraphQL, and if Python powers your backend, sharpen your fundamentals with how to learn Python fast.