DevOps Tutorials, Guides & Best Practices

You ran docker compose down to “just stop” your stack, and suddenly your containers are gone. Or you want to stop everything before changing config, but you don’t want Docker to remove containers/networks or risk nuking volumes.

For adjacent lifecycle commands, compare this with Docker Compose Restart Policy, Docker Compose Up, and Docker Compose Down.

docker compose stop is the boring, safe option for those cases.

Quick takeaway: docker compose stop stops running containers in a Compose project but keeps the containers, networks, and volumes. Use it when you want a reversible pause, not a cleanup.

TL;DR

• Use docker compose stop when you want to pause a Compose stack without removing anything.
• Use docker compose down when you want a clean slate (and you understand what will be removed).
• If you want to stop + remove containers but keep volumes, you can use down without -v.

What `docker compose stop` does (and doesn’t)

It does

• Stops the containers for the current Compose project.
• Stops containers gracefully using Docker’s stop behavior (SIGTERM, then SIGKILL after the timeout).

It doesn’t

• Remove containers.
• Remove networks.
• Remove images.
• Remove volumes.

Basic usage

# Stop the services (containers) for the current project
docker compose stopCode language: PHP (php)

After running it, docker compose start will start the existing containers again.

# Start previously stopped containers
docker compose startCode language: PHP (php)

Important flags

Timeout flag

If you have services that need a clean shutdown (databases, queues), set a higher timeout.

# Give containers 60 seconds to stop gracefully
docker compose stop --timeout 60Code language: PHP (php)

Sources:

• docker compose stop docs: https://docs.docker.com/reference/cli/docker/compose/stop/
• Docker stop signal behavior: https://docs.docker.com/reference/cli/docker/container/stop/

“Stop” vs “Down”: pick the safe command

Command	Best For	What Stays	Main Risk
docker compose stop	Pausing a stack safely	Containers, networks, volumes, images	Ports may remain occupied if another process is involved
docker compose down	Removing project containers and the default network	Named volumes by default	Containers are recreated on the next up
docker compose down -v	Intentional full local reset	Images, unless --rmi is used	Named volume data is deleted

Use this quick decision table mentally:

• You want to pause and resume later, keep container state: use stop.
• You want containers recreated on next up: use down.
• You suspect a bad container state and want a rebuild: down then up --build.

Volume safety nuances (read this once, avoid pain)

• By default, docker compose down removes containers + networks (including the default network). It does **not** remove named volumes unless you pass -v / --volumes.
• Networks and volumes marked as external are never removed.
• Anonymous volumes are not removed by default. But because they don’t have stable names, they may not be automatically remounted on a subsequent up. For data that must persist, prefer a **named volume** or a **bind mount**.

Sources:

• docker compose down docs: https://docs.docker.com/reference/cli/docker/compose/down/

Common trap: docker compose down removes containers. If your app wrote data into the container filesystem (not volumes), that data is gone when containers are removed.

Safe reset recipes (copy/paste)

1) Pause everything (reversible)

docker compose stop

Use this before editing config, switching branches, or freeing ports temporarily.

2) Restart the stack cleanly without deleting anything

docker compose restart

This is often enough when a service is stuck, but you don’t want to remove containers.

3) Recreate containers but keep volumes (most common local “reset”)

# Stop + remove containers and default network, keep named volumes
docker compose down

docker compose up -dCode language: PHP (php)

If you need a rebuild:

docker compose up -d --build

4) Full wipe (containers + volumes). Use only when you truly want to delete data

# WARNING: this deletes named volumes for the Compose project
docker compose down -vCode language: PHP (php)

Common mistakes

• Running down when you only meant “stop”.
• Assuming your DB data is safe when it was not stored in a named volume.
• Stopping the wrong Compose project because you’re in the wrong directory.

Troubleshooting

“I ran `stop` but ports are still in use”

• Confirm containers stopped:

docker compose ps

• If something is still listening, list containers and check:

docker ps

“`stop` is slow or hangs”

• Increase timeout or inspect the service logs:

docker compose logs --tail 200 <service>Code language: HTML, XML (xml)

Use these answers as a quick safety check before choosing between stop, down, and down -v.

FAQ