docker-compose / docker compose 报 command not found（Compose 没装或没接线）

你会遇到什么

两种典型形态：WSL 里 docker-compose --version 报 The command 'docker-compose' could not be found in this WSL 2 distro（Docker Desktop 的 shim 在提示），或 docker compose 报 docker: unknown command: docker compose。

compose 不是 docker CLI 内置子命令，而是独立插件——装了 docker 不等于装了 compose。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

Docker CLI 的插件机制：docker <子命令> 会去 ~/.docker/cli-站内文档 和 /usr/libexec/docker/cli-站内文档 找名为 docker-<子命令> 的可执行文件。compose 就是 docker-compose 插件：没装 = unknown command。

而 WSL 里那条「could not be found in this WSL 2 distro」是 Docker Desktop 装在 Windows PATH 里的 shim 在说话——它检测到当前发行版没激活 Desktop 集成、也没装原生插件。

docker compose = docker CLI 发现并执行 docker-compose 插件二进制；docker-compose（独立命令） = 直接执行同名单二进制。两条路最终都要求 compose 二进制存在于 CLI 插件目录或 PATH。

Ubuntu 的 docker-compose-v2 包安装后放到 /usr/libexec/docker/cli-站内文档，docker compose` 立即可用；

而 PATH 里残留的 Docker Desktop shim（/mnt/c/Program Files/Docker/Docker/resources/bin/）在 WSL 里被优先命中时，会先检查 WSL 集成再决定报什么错。

确定性推论：先分清「谁在回答」——报 unknown command: docker compose = 插件目录里没这东西，装 docker-compose-v2 或下载官方插件二进制到 `~/.docker/cli-站内文档；

报 could not be found in this WSL 2 distro = Desktop shim 优先，二选一：启用 Desktop 的 WSL 集成，或装原生插件让 shim 让路。

一步步来

1. 确认 docker 本体在 — 必做

docker --version

2. 按报错形态分流 — 按诊断结果

• docker: unknown command: docker compose → 装插件：sudo apt-get install -y docker-compose-v2（Debian/Ubuntu）或下载官方插件二进制到 `~/.docker/cli-站内文档（其它发行版，见 Docker 官方 Compose 安装文档）。
• The command 'docker-compose' could not be found in this WSL 2 distro → 这是 Desktop shim：要么在 Docker Desktop 设置里打开该发行版的 WSL 集成（用 Desktop 的 compose），要么装原生插件后用 type docker-compose 确认 shim 不再抢先。

3. 验证接线成功 — 必做

docker compose version
# 期望输出：Docker Compose version v2.x.x（实测 2.40.3）

怎么确认修好了

docker compose version 输出版本号且 exit 0；在含 docker-compose.yml 的目录里 docker compose config 能解析出服务列表。

其它环境的表现

症状

# 形态 1：Desktop shim 在 WSL 里
The command 'docker-compose' could not be found in this WSL 2 distro.
We recommend to activate the WSL integration in Docker Desktop settings.

# 形态 2：原生 CLI 没插件
docker: unknown command: docker compose

Run 'docker --help' for more information

特征：docker 本体命令正常，只有 compose 相关命令报错；形态 2 是「CLI 在，插件不在」，形态 1 是「Windows 侧 shim 在，WSL 集成/原生插件不在」。

原因

compose 是 docker CLI 的插件（docker-compose 二进制放在 CLI 插件目录），不是 docker 本体的一部分。没装插件 = unknown command；WSL 里 Desktop shim 命中时给「激活 WSL 集成」的引导文案。修复本质是把 compose 插件装到 CLI 能发现的位置。

解法

1. 原生：sudo apt-get install -y docker-compose-v2（Debian/Ubuntu），或官方插件二进制放 `~/.docker/cli-站内文档；
2. Desktop 用户：设置里开 WSL 集成；
3. 验证：docker compose version。

相关 canonical

按「前置 → 同根 / 同域 / 相关」读：

• 相关（报错相近，根因不同）：
• Docker daemon 连不上（compose 连的是同一个 daemon socket）