DevOps Tutorials, Guides & Best Practices

Quick answer: docker compose down stops and removes all containers, networks, and optionally volumes created by docker compose up. Unlike stop, it deletes containers — so you get a clean slate on the next up. Use it when you need a full reset, not just a pause.

What docker compose down actually does

When you run docker compose down from the directory containing your compose.yml, Docker:

1. Stops all running containers that belong to the current Compose project.
2. Removes those containers (they’re gone — not just paused).
3. Removes the default network (project_default) that Compose created for inter-service communication.

By default, it does not remove named volumes, images, or external resources. That’s by design — your data survives a down unless you explicitly tell Compose to wipe it.

It does

• Stop running containers for the current Compose project
• Remove those containers (IDs, logs, runtime state — all gone)
• Remove the default network (project_default)

It doesn’t (by default)

• Remove named volumes — data persistence is preserved
• Remove built or pulled images — they stay in your local registry
• Remove external resources (networks/volumes declared as external: true)
• Affect other Compose projects — each project is isolated

Tip: Run docker compose --dry-run down (Compose v2.19+) to preview exactly what will be removed before committing. No containers are stopped or deleted during a dry run.

Basic usage

The simplest form runs from the directory with your Compose file:

# Run from the directory with your compose.yaml / docker-compose.yml
docker compose downCode language: YAML (yaml)

If you have multiple Compose files (common in multi-environment setups):

# Two-file setup: base config + production overrides
docker compose -f compose.yaml -f compose.prod.yaml downCode language: YAML (yaml)

If you set a custom project name (stacks share the same name space):

# Target a specific project by name
docker compose -p myproject downCode language: YAML (yaml)

Flags that matter (with examples)

Flag	What it does	Risk level
--dry-run (top-level flag)	Preview via docker compose --dry-run down — no changes	🟢 Safe
--remove-orphans	Remove containers not in current compose file	🟡 Moderate
--rmi local	Remove images built by the project (no tags)	🟡 Moderate
--rmi all	Remove all images used by the project	🟠 Higher
-v / --volumes	Delete named + anonymous volumes	🔴 Data loss
-t / --timeout	Seconds to wait before SIGKILL (default: 10)	🟢 Safe

-v / --volumes — data deletion

This is the most dangerous flag. It removes both named and anonymous volumes attached to the project’s containers. If your database stores data in a named volume, down -v permanently deletes it.

# WARNING: deletes all volumes including named ones
docker compose down -v

# Safety check: list volumes first
docker volume ls
# Then decide if -v is what you wantCode language: YAML (yaml)

For a deeper dive on the -v flag and safe reset patterns, see our dedicated guide: Docker Compose Down -v (Volumes): What It Deletes and Safe Reset Recipes.

--rmi — image cleanup

Two modes:

# Remove only images built by this Compose project (no explicit tag)
docker compose down --rmi local

# Remove ALL images referenced by any service in the project
docker compose down --rmi all

# Combine with -v for a full nuclear reset
docker compose down -v --rmi allCode language: YAML (yaml)

Warning: down -v --rmi all is a full nuclear option. It deletes volumes, images, containers, and the network in one command. Use it only when you genuinely need to rebuild from scratch — like testing a CI pipeline locally.

--remove-orphans — container cleanup

Removes containers that belong to the Compose project but are no longer defined in the current compose file. This happens when you rename or remove a service without a clean down first.

# Clean up orphan containers after service changes
docker compose down --remove-orphansCode language: YAML (yaml)

-t / --timeout — graceful shutdown window

Controls how long Docker waits after sending SIGTERM before forcing SIGKILL. Default is 10 seconds. Increase this if your services need time for graceful cleanup (draining connections, flushing buffers, writing checkpoints).

# Give services 30 seconds for graceful shutdown
docker compose down -t 30Code language: YAML (yaml)

Stop vs Down vs Down -v: which one do you need?

Action	Stops containers	Removes containers	Removes network	Removes volumes	Best for
docker compose stop	✅	❌	❌	❌	Brief pause, restart with same state
docker compose down	✅	✅	✅	❌	Reset containers, keep data
docker compose down -v	✅	✅	✅	✅	Full teardown, wipe everything

How down fits into the Docker Compose lifecycle

Each Docker Compose command handles a specific phase of the container lifecycle. Here’s how they fit together:

• up — create and start everything from your compose file
• stop — stop containers without removing them (data + config preserved)
• down — stop and remove containers + network (data preserved unless -v)
• restart — control what happens when a container exits (policy, not a command)

Think of it as a spectrum: pause → reset → wipe. stop pauses, down resets, and down -v wipes.

Production note: docker compose down is primarily a development tool. In production, container orchestration (Kubernetes, Swarm, Nomad) handles lifecycle management differently. Use Compose for local dev, CI, and single-host deployments — not for orchestrating production clusters.

Cheat sheet: common patterns

# Standard teardown — keep volumes and images
docker compose down

# Preview what will happen — use top-level flag (no changes)
docker compose --dry-run down

# Reset containers AND orphan cleanup
docker compose down --remove-orphans

# Full data wipe — deletes named volumes too
docker compose down -v

# Clean rebuild: wipe everything, then rebuild and start
docker compose down -v --rmi all
docker compose up --build -d

# Multi-file project down
docker compose -f compose.yml -f compose.override.yml down

# Target specific project by name
docker compose -p myproject down

# Slow graceful shutdown (30s timeout)
docker compose down -t 30Code language: YAML (yaml)

FAQ