docker compose down command

Docker command reference

docker compose downUsed to stop and deletedocker compose upall containers, networks, and related resources that were started.

When executingdocker compose upAfter starting a set of services, Docker automatically creates containers, networks, and even anonymous data volumes.

If only usingdocker compose stop, the containers are only paused, but they still occupy disk space and retain network configuration; when started next time, the old state may cause conflicts.

docker compose downThen there is one-click thorough cleanup: stop containers, delete containers, remove networks, and restore the environment to a clean state.

The following flowchart shows the complete execution chain of the down command:

If you are not sure whether the current environment is clean, first usedocker compose psCheck the running containers, then decide whether to run down.

Quick start

Simplest usage: in a directory containingdocker-compose.ymlExecute in the directory where the file is located:

# 进入 Compose 项目目录
cd ~/myproject

# 一键停止并清理所有资源
docker compose down

After execution, the terminal usually outputs something like the following:

[+] Running 3/3
 Container myproject-web-1     Removed    1.2s
 Container myproject-db-1      Removed    0.8s
 Network myproject_default     Removed    0.3s

At this point:

All containers started by Compose have been stopped and deleted.
The project-specific network has been removed.
Data volumesRetained by default(to prevent accidental data deletion)

Command option quick reference

The following aredocker compose downComplete list of supported options:

Options	Abbreviation	Description	Default value
--volumes	-v	Delete named data volumes defined in the Compose file, as well as anonymous data volumes mounted by containers.	Do not delete
--remove-orphans	None	Delete orphan containers corresponding to services that no longer exist in the Compose file.	Do not delete
--rmi <type>	None	Delete the images used by services; type is optional.all(All) orlocal(locally built only)	Do not delete
--timeout	-t	Timeout (in seconds) for stopping containers; after timeout, force kill.	10
--dry-run	None	Only print the operations that will be performed, without actually executing them (v2.21+).	Do not enable

Default behaviors that need the most attention:Data volumes are not deleted by defaultThis means that even if you execute down, the data in the database remains in the data volume and will be restored next time you run up. This is a protection mechanism, but if you really want to clean up thoroughly, remember to add-v。

Detailed usage

Basic usage: stop and clean up

Run directly in the project directory without any options:

# 停止并删除容器和网络，保留数据卷
docker compose down

This is equivalent to executing in sequence:

docker compose stop       # 停止所有容器
docker compose rm -f      # 强制删除所有容器
docker network rm &lt;网络名&gt;  # 删除项目网络

Also delete data volumes: -v / --volumes

When you need to completely clear the environment—including persistent content such as database data and caches—add-v：

# 删除容器、网络以及 Compose 文件中定义的所有具名数据卷
docker compose down -v

The following is a complete comparison example to help understand-vImpact:

Example

# docker-compose.yml file content
services:
web:
image: nginx
ports:
- "8080:80"
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: example123
volumes:
- db_data:/var/lib/mysql # named volumes

volumes:
db_data: # define named volumes

# 不带 -v：db_data 数据卷保留，数据库中的数据不丢失
$ docker compose down
[+] Running 3/3
 Container test-web-1  Removed
 Container test-db-1   Removed
 Network test_default   Removed

# 带 -v：db_data 数据卷被删除，数据库数据永久丢失
$ docker compose down -v
[+] Running 4/4
 Container test-web-1   Removed
 Container test-db-1    Removed
 Volume test_db_data    Removed
 Network test_default   Removed

Executing in a production environmentdown -vBefore [doing so], be sure to think twice—once a data volume is deleted, the data is unrecoverable. It is recommended to back up data first, or use it only in non-production environments.-v。

Clean up orphan containers: --remove-orphans

When you delete a service definition from your docker-compose.yml file, but the container of that service still remains, these containers are called "orphan containers."

Example

# docker-compose.yml
services:
app:
image: nginx
networks:
- shared_network # reference external network

networks:
shared_network:
external: true # external network, down will not delete it

volumes:
shared_data:
external: true # external volume, down -v will not delete it either

This is reasonable: external resources may be shared by multiple Compose projects and should not be cleaned up by a single project.

Startup order of container dependencies

down stops containers in reverse order, that is, stops the dependent party first, then the depended-on party, opposite to the startup order during up, ensuring dependencies are correctly released.

Compatibility with docker-compose (legacy version)

If you are using an older versiondocker-compose(with a hyphen), the command format is:

$ docker-compose down -v

The new Docker Compose v2 integrates Compose functionality into the Docker CLI, and the command becomesdocker compose(Space-separated.) The parameters of the two are exactly the same, but it is recommended to consistently use the new format.

FAQ

Q: After running down, are the containers still running?

Possible reason: these containers were not created by the current Compose file, but were started viadocker runor started by other Compose files.

usedocker psView container details to confirm whether the container name prefix matches the Compose project name.

Q: Disk space not released after down -v?

Check whether unused images are taking up space:

$ docker image ls        # 查看镜像列表
$ docker image prune -a  # 清理未使用的镜像

Docker does not automatically clean up images; you need to manually rundocker image pruneor usedown --rmi allClean up together.

Q: How to safely execute down in a script?

Example

#!/bin/bash
# Safe cleanup script: first confirm the project is running, then execute down

PROJECT_DIR="/opt/example-app"

if [ -f "$PROJECT_DIR/docker-compose.yml" ]; then
cd "$PROJECT_DIR"
# First use ps to check whether there are running services
if docker compose ps --status running | grep -q .; then
echo "Stopping EXAMPLE project..."
docker compose down --remove-orphans
echo "Cleanup completed"
else
echo "Project is not running, skipping down operation"
fi
else
echo "Error: cannot find docker-compose.yml file"
exit 1
fi

This script performs basic path checks and state judgments before cleanup to avoid accidental operations.

Docker command reference

other extensions