Docker Compose Cheatsheet - Command Reference
For developers who need to bring up, stop, and upgrade a whole stack at once — database, cache, backend, frontend — as a single unit. Compose value is not in the commands themselves but in a single docker-compose.yml that pins down the network, dependencies, and config between services so the whole environment can be started and stopped repeatedly. By the end you can bring the stack up with up, find the failing service with logs, clean up fully (and safely) with down -v, and scale out with --scale.
Typical Use Case
Orchestrate multi-container apps with one YAML: bring up/down a whole stack, manage networks and shared volumes, view aggregated logs, scale services, and troubleshoot dependency order, port conflicts and failed health checks.
Start & Stop 5
docker compose up -ddocker compose up -d --builddocker compose stopdocker compose downdocker compose restart svcLogs & Status 5
docker compose psdocker compose logs -f svcdocker compose logs --tail=100 svcdocker compose topdocker compose port svc 80Config & Build 5
docker compose configdocker compose builddocker compose pulldocker compose exec svc shdocker compose run --rm svc cmdNetwork & Volume 5
docker compose up -d --scale svc=3docker network lsdocker compose down -vdocker volume lsdocker compose config --volumesFAQ 5
Q: What is the difference between docker compose up and docker compose start?Q: How do I rebuild images?Q: How do I view Compose project logs?Q: How do I start only a specific service?Q: How do I remove all containers and volumes?Parameter matrix
| Parameter | Effect | Example |
|---|---|---|
up -d | Creates and starts every service in the background | docker compose up -d |
down | Stops and removes the containers and networks, while keeping named volumes by default | docker compose down |
ps | Shows the running state of each service | docker compose ps |
logs | Shows the aggregated log stream | docker compose logs -f web |
exec | Runs a command inside a service that is already up | docker compose exec web sh |
--build | Rebuilds the images before starting them | docker compose up -d --build |
scale / up --scale | Sets the replica count for one service | docker compose up -d --scale web=3 |
restart | Restarts a service | docker compose restart web |
config | Validates and expands the final resolved configuration | docker compose config |
pull | Fetches only the images the services actually use | docker compose pull |
Common pitfalls
SymptomOne service restarts in a loop, or sits at starting forever, after up.
CauseA dependency is not ready yet: web waits on db, and depend_on only waits for the container to start, not for it to become healthy. A port clash is the other suspect.
FixGive the dependency a healthcheck and gate on depends_on with condition: service_healthy; then read docker compose logs for the actual error.
SymptomContainers cannot reach each other by service name.
CauseThe services are not on the same user-defined network, or something still points at localhost, which inside a container means the container itself.
FixCompose creates a network for you, so use the service name, db, as the host and put that into the connection string instead of 127.0.0.1.
SymptomAn edit to docker-compose.yml has no effect on up.
CauseThe file was changed without --build, and the old container was never recreated.
FixUse docker compose up -d --build after touching build settings; for runtime-only changes, down first and then up.
SymptomThe data is gone after down.
CauseIt was written to the container layer rather than a named volume, and down deletes containers.
FixPersist with a named volume in the compose file; down keeps volumes by default, so only add -v when you truly mean to discard them.
SymptomPort or network name clashes between projects.
CauseCompose derives the same default project name for both, so the generated resource names collide.
FixSeparate them with -p or COMPOSE_PROJECT_NAME, or name the networks and volumes explicitly in the compose file.
SymptomA code change does not show up in the image because the build cache is reused.
CauseCOPY sits above the dependency installation, or .dockerignore is misconfigured so a layer keeps hitting the cache.
FixPut the rarely changing layers first, force a rebuild with --build, and re-check which directories .dockerignore excludes.
Troubleshooting
1Validate the config before starting
docker compose configIt expands and checks the YAML, so a typo fails here instead of taking the whole stack down.
2See per-service state and exit codes
docker compose psThe State column reports Exit or Restarting directly, which names the failing service.
3Tail one service logs
docker compose logs -f webRead the live output of the service that is stuck at startup.
4Debug inside a running service
docker compose exec web shCheck network reachability, files and processes from within the container itself.
Command Examples
Start the stack in the background and rebuild images first
docker compose up -d --buildWithout -d the command stays attached and streams every service log; --build makes sure you are running the freshly built image rather than a cached one.
Follow one service log, limited to the last 100 lines
docker compose logs --tail=100 -f svcDropping svc gives the aggregated log of every service; --tail caps how far back it reads so you are not scrolled away by thousands of lines on arrival.
Get a shell inside a running service container
docker compose exec svc shThe service has to be up for exec to work; for a one-shot command use run --rm, which drops the temporary container as soon as it finishes.
Scale one service up to three instances
docker compose up -d --scale svc=3A scaled service must not pin a fixed host port, otherwise the extra instances collide on the same host port and refuse to start.
Common Pitfalls
- docker compose down -v removes named volumes along with the containers, and that data cannot be recovered, so back up any volume that matters before running it in production.
- Never pin a host port on a service you intend to scale with --scale; the extra instances fight over that port and fail to start.
- After editing the compose file do not reach for restart alone: it neither reparses the configuration nor recreates containers, so validate with config and then run up -d.
- Several compose projects on one machine derive network and volume names from the project name, so collisions silently clobber each other; use -p to keep the project names distinct.
- build uses the layer cache by default; when your code change is mysteriously missing from the image, add --no-cache for a full rebuild and check again.
Tips
- Compose commands look for docker-compose.yml in the current directory by default; use -f for other files, -p for project name.
- down does not remove volumes by default — add -v to remove them; back up production volumes first, named volume data is irrecoverable.
- Services scaled with --scale must not use fixed host ports, or multiple instances will conflict.
FAQ
Should I use docker compose stop or docker compose down?
It depends on whether you want to keep the containers. stop halts the services but leaves the containers in place so you can bring them back quickly. down halts them and removes the containers along with the project network, so the next start has to create everything again. If you also want the data volumes gone, add -v to down, but that permanently wipes the named volumes, so back them up first in any production setting.
How does docker compose run --rm differ from docker compose up -d?
up -d brings the whole stack up in the background and the containers keep running. run --rm targets a single service for a one-shot command and then removes that throwaway container immediately because of --rm. The first suits long-lived services, the second suits migrations, ad-hoc database queries, and anything that should leave nothing behind.
What do compose volumes look like in docker volume ls, and how do I list them?
They are named with the project name and the volume name joined by an underscore, so myapp_db is the db volume of project myapp rather than something you created by hand. To enumerate what the current compose file actually declares, run docker compose config --volumes and get the authoritative list instead of guessing from the YAML.
How do I find out which host port a service port ended up on?
Pass the service name and the in-container port to docker compose port svc 80 and it prints the real port on the host. This matters most when the host port is 0 or otherwise left to the system to assign, because the compose file itself will not tell you the final number.
In what order should I refresh images and rebuild?
Pull first when the base images have gone stale, then run docker compose build if your own source changed, and finally docker compose up -d so the new image is what actually runs. If you want it in one step, docker compose up -d --build builds before starting. When a cache is suspected of hiding your edits, add --no-cache to build for a full rebuild.
Official References
Each command links to its official documentation below, so you can verify the latest usage and read deeper.
Maintained by LaoHand
Publicly updated on Jul 21, 2026, continuously proofread against official docs.
Contact Us
Wrong command or description? Send us corrections, business inquiries or product feedback by email.
Contact Us