docker compose down 命令

Docker 命令大全

docker compose down 用于停止并删除由 docker compose up 启动的所有容器、网络及相关资源。

当执行 docker compose up 启动一组服务后，Docker 会自动创建容器、网络，甚至匿名数据卷。

如果只用 docker compose stop，容器只是暂停运行，但依然占用磁盘空间、保留网络配置，下次启动时旧状态可能引发冲突。

docker compose down 则是一键彻底清理：停止容器、删除容器、移除网络，让环境回到干净状态。

下面的流程图展示了 down 命令的完整执行链路：

如果你不确定当前环境是否干净，先用 docker compose ps 查看运行中的容器，再决定是否执行 down。

快速开始

最简单的用法：在包含 docker-compose.yml 文件的目录下执行：

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

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

执行后，终端通常会输出类似以下内容：

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

此时：

所有由 Compose 启动的容器已被停止并删除
项目专属网络已被移除
数据卷默认保留（防止误删数据）

命令选项速查

以下是 docker compose down 支持的完整选项列表：

选项	简写	说明	默认值
--volumes	-v	删除 Compose 文件中定义的具名数据卷，以及容器挂载的匿名数据卷	不删除
--remove-orphans	无	删除 Compose 文件中已不存在的服务所对应的孤儿容器	不删除
--rmi <type>	无	删除服务使用的镜像，type 可选 all（全部）或 local（仅本地构建的）	不删除
--timeout	-t	容器停止的超时时间（秒），超时后强制杀死	10
--dry-run	无	仅打印将要执行的操作，不实际执行（v2.21+）	不启用

最需要注意的默认行为：数据卷默认不会被删除。这意味着即使你执行了 down，数据库中的数据依然保留在数据卷中，下次 up 时会恢复。这是一个保护机制，但如果你确实想彻底清理，记得加上 -v。

详细用法

基础用法：停止并清理

在项目目录下直接执行，不带任何选项：

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

这等价于先后执行：

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

连带删除数据卷：-v / --volumes

当你需要彻底清空环境——包括数据库数据、缓存等持久化内容时，加上 -v：

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

以下是一个完整的对比示例，帮助理解 -v 的影响：

实例

# docker-compose.yml 文件内容
services:
web:
image: nginx
ports:
- "8080:80"
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: runoob123
volumes:
- db_data:/var/lib/mysql # 具名数据卷

volumes:
db_data: # 定义具名数据卷

# 不带 -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

在生产环境中执行 down -v 前务必三思——数据卷一旦删除，数据将不可恢复。建议先备份数据，或在非生产环境中才使用 -v。

清理孤儿容器：--remove-orphans

当你的 docker-compose.yml 文件中删除了某个服务定义，但该服务的容器还残留时，这些容器被称为「孤儿容器」。

实例

# docker-compose.yml
services:
app:
image: nginx
networks:
- shared_network # 引用外部网络

networks:
shared_network:
external: true # 外部网络，down 不会删除它

volumes:
shared_data:
external: true # 外部数据卷，down -v 也不会删除它

这是合理的：外部资源可能被多个 Compose 项目共享，不应由单个项目清理。

容器依赖的启动顺序

down 逆序停止容器，即先停止依赖方，再停止被依赖方，和 up 时的启动顺序相反，确保依赖关系正确释放。

与 docker-compose（旧版）的兼容性

如果你使用的是旧版 docker-compose（带连字符），命令格式为：

$ docker-compose down -v

新版 Docker Compose v2 将 Compose 功能集成进了 Docker CLI，命令变为 docker compose（空格分隔）。两者参数完全一致，但建议统一使用新版格式。

常见问题

Q: down 之后容器还在运行？

可能的原因：这些容器不是由当前 Compose 文件创建的，而是通过 docker run 或其他 Compose 文件启动的。

用 docker ps 查看容器详情，确认容器名称前缀是否与 Compose 项目名称匹配。

Q: down -v 之后磁盘空间没释放？

检查是否有未使用的镜像占用空间：

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

Docker 不会自动清理镜像，需要手动执行 docker image prune 或用 down --rmi all 一并清理。

Q: 如何在脚本中安全地执行 down？

实例

#!/bin/bash
# 安全清理脚本：先确认项目在运行，再执行 down

PROJECT_DIR="/opt/runoob-app"

if [ -f "$PROJECT_DIR/docker-compose.yml" ]; then
cd "$PROJECT_DIR"
# 先用 ps 检查是否有运行中的服务
if docker compose ps --status running | grep -q .; then
echo "正在停止 RUNOOB 项目..."
docker compose down --remove-orphans
echo "清理完成"
else
echo "项目未运行，跳过 down 操作"
fi
else
echo "错误：找不到 docker-compose.yml 文件"
exit 1
fi

这个脚本在清理前做了基本的路径检查和状态判断，避免误操作。