# Docker Compose cheat sheet

> Docker Compose cheat sheet: the compose.yaml file (services, build, ports, volumes, environment, depends_on) and docker compose up/down/logs/exec — verified against the official docs.

- Page URL: https://itinsighthub.com/docker/compose/
- Markdown variant of this page: append `?format=md` to any URL on this site or send `Accept: text/markdown`.
- Full site index for AI assistants: https://itinsighthub.com/llms.txt
- Full site export: https://itinsighthub.com/llms-full.txt

# Docker Compose cheat sheet

Docker Compose defines a multi-container application in one declarative file — by default `compose.yaml` — and starts the whole stack with a single command. Where `docker run` is one container, Compose is *many*, wired together with shared networks and volumes.

The modern command is `docker compose` (no hyphen), the Compose V2 plugin that ships with current Docker Desktop and Engine. The old `docker-compose` (V1) standalone is deprecated and missing newer features, so everything here uses the plugin form.

Published August 22, 2026

## The compose.yaml file

A two-service app: a web service and its database

```
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data

  web:
    build: .
    ports:
      - "8080:3000"
    environment:
      DATABASE_URL: postgres://db:5432/app
    depends_on:
      - db

volumes:
  pgdata:
```

The keys that matter

- **services::** the containers to run — one entry per service, names become DNS hostnames on the shared network
- **build: .:** build an image from a Dockerfile in the given directory (vs image: which pulls one)
- **image: postgres:16:** pull and run a pre-built image
- **ports: "8080:3000":** publish host:container ports, same as -p
- **volumes: - pgdata:/var/lib/...:** named volume mounts, same as -v
- **environment::** environment variables (a map, or - KEY=value list form)
- **depends_on::** start this service only after the listed ones (ordering, not readiness)

Compose v2 no longer needs a top-level version: field — it was an obsolete Compose V1-era key and modern versions ignore it. Services reach each other by service name (db, web) over the project's default network, which is why the connection string above uses db:5432 instead of localhost. Note that depends_on only orders startup; for true "wait until ready" you need a healthcheck plus depends_on: condition: service_healthy.

## The docker compose commands

*The compose command set — all run in the directory containing compose.yaml*

| Command | What it does |
| --- | --- |
| docker compose up -d | create and start the whole stack, detached (add --build to rebuild images first) |
| docker compose down | stop and remove the stack (add -v to also delete named volumes) |
| docker compose ps | list the stack's containers and their state |
| docker compose logs -f web | follow logs for one service (omit the name for all) |
| docker compose exec web bash | open a shell inside a service container |
| docker compose build | build/rebuild the images defined with build: |
| docker compose restart web | restart one service |
| docker compose pull | pull the latest images without starting anything |

## One-off and admin tasks

Run commands without starting the whole stack

```
# Run a one-off command in a fresh container of a service
docker compose run --rm web npm run migrate

# Check the config and expand variables without running anything
docker compose config

# Show resource usage for the stack
docker compose stats

# Stop everything but keep the containers (down removes them)
docker compose stop
```

## References

- [Compose file reference](https://docs.docker.com/compose/compose-file/) — every key, officially documented.
- [docker compose CLI reference](https://docs.docker.com/compose/reference/) — the full command list for the V2 plugin.

## FAQ

**What is the difference between docker compose and docker-compose?**

docker compose (no hyphen) is the Compose V2 plugin, part of current Docker Desktop and Engine, and the actively developed implementation. docker-compose is the older V1 standalone Python binary, now deprecated. They run the same compose files for everyday use, but new features, the removal of the version field, and bug fixes are only in V2, so use docker compose.

**How do I rebuild and restart my stack?**

docker compose up -d --build rebuilds images where the build context changed and recreates only the affected containers, leaving unchanged services running. To also pick up a changed image tag for an image: service, add docker compose pull first. A full reset is docker compose down followed by up.

**What does docker compose down -v do?**

down stops and removes the stack's containers and networks; adding -v also deletes the named volumes declared in the file. Because volumes hold the persistent data, -v is destructive — leave it off if you want to keep database data between restarts.

**How do services find each other in Compose?**

Compose creates a default network and puts every service on it, with DNS entries matching the service names. A service named db is reachable from web as the hostname db on the container's port. No ports: mapping is needed for service-to-service traffic — ports: is only for exposing a service to the host.

## Related tools

- [IPv4 subnet calculator](https://itinsighthub.com/subnet-calculator/) — break any CIDR block into network, range, broadcast and usable hosts.
- [IP range to CIDR](https://itinsighthub.com/ip-range-to-cidr/) — turn an arbitrary address range into its minimal covering CIDR blocks.
- [VLSM calculator](https://itinsighthub.com/vlsm-calculator/) — split a block into right-sized subnets by host requirements.

---

© 2026 ITInsightHub · [About](https://itinsighthub.com/about/) · [Contact](https://itinsighthub.com/contact/) · [Privacy](https://itinsighthub.com/privacy/)