Docker Compose v2 版本启动报错 command not found 怎么办

遇到 docker-compose: command not found 报错，最可能的原因是你安装了 Docker Compose v2 插件，但仍在使用 v1 版本的独立命令写法，或者插件未正确加入环境变量。

先说结论：这通常是命令语法变更或插件缺失导致的，优先尝试改用 docker compose 命令。

命令速用版

如果你急需启动服务，先尝试将命令中的横杠去掉，用空格代替：

docker compose up -d

如果系统提示 docker: 'compose' is not a docker command，说明插件未安装，需要根据系统类型安装插件。

Docker Compose v1 是一个独立的二进制文件，命令是 docker-compose（带横杠）。从 v2 开始，Compose 被重构为 Docker CLI 的一个插件，命令变成了 docker compose（空格分隔）。

很多教程或旧脚本仍然沿用 v1 的写法。如果你的系统只安装了 v2 插件而没有兼容链接，直接运行旧命令就会报 command not found。

1. 检查当前命令写法

确认你在终端输入的是 docker-compose 还是 docker compose。v2 版本推荐使用空格写法。

2. 安装 Compose 插件

如果 docker compose version 也报错，说明插件没装。以 Ubuntu 为例：

sudo apt-get update
sudo apt-get install docker-compose-plugin

macOS Docker Desktop 通常默认内置了 v2 插件，无需单独安装。Windows 同理。

3. 兼容旧命令（可选）

如果必须使用 docker-compose 旧命令（例如配合旧脚本），可以创建软链接，但官方更建议修改脚本：

sudo ln -s /usr/libexec/docker/cli-plugins/docker-compose /usr/bin/docker-compose

注意：不同系统插件路径可能不同，需先查找实际路径。

运行以下命令查看版本信息，如果能正常输出版本号且无报错，说明环境已就绪：

docker compose version

随后尝试启动一个测试项目，观察容器状态是否为 Up。

1. CI/CD 脚本硬编码

很多自动化流水线里写死了 docker-compose，升级服务器后容易失败。建议在流水线镜像中明确指定包含插件的版本。

2. 权限问题

安装插件后，确保当前用户有权限执行 docker 命令，否则可能报权限拒绝而非找不到命令。

3. 路径不一致

手动安装二进制文件时，如果没放到 /usr/local/bin 或 CLI plugins 目录，Docker 可能识别不到插件。

Docker Official Documentation, "Install the plugin", https://docs.docker.com/compose/install/linux/
Docker Official Documentation, "Compose V2 and backwards compatibility", https://docs.docker.com/compose/migrate/