我的问题情况 #

在Debian 12（Bookworm）服务器上执行apt update && apt upgrade完成系统和软件更新后，我遇到了Docker Compose的API版本兼容问题：

• 当手动指定API版本时，docker compose ps能正常执行：

  DOCKER_API_VERSION=1.52 docker compose ps
  

• 但直接运行docker compose ps时，会弹出错误：

  Error response from daemon: client version 1.42 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version
  

下面是我的系统和Docker相关版本信息，供参考：

系统版本信息

执行cat /etc/os-release输出：

PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"

Docker版本信息

执行docker version输出：

Client: Docker Engine - Community
Version: 29.0.0
API version: 1.52
Go version: go1.25.4
Git commit: 3d4129b
Built: Mon Nov 10 21:46:24 2025
OS/Arch: linux/amd64
Context: default

Server: Docker Engine - Community
Engine:
Version: 29.0.0
API version: 1.52 (minimum version 1.44)
Go version: go1.25.4
Git commit: d105562
Built: Mon Nov 10 21:46:24 2025
OS/Arch: linux/amd64
Experimental: false
containerd:
Version: v2.1.5
GitCommit: fcd43222d6b07379a4be9786bda52438f0dd16a1
runc:
Version: 1.3.3
GitCommit: v1.3.3-0-gd842d771
docker-init:
Version: 0.19.0
GitCommit: de40ad0

问题分析 #

从版本信息能看出来，我的Docker客户端和服务端的API版本都是1.52，完全满足服务端要求的最低1.44版本标准。那为啥直接用docker compose会调用旧的1.42 API呢？大概率是Docker Compose插件的版本太老，没跟上Docker Engine的版本更新，导致它默认使用了不匹配的旧API版本。

解决方法分享 #

1. 先检查当前Compose版本

先确认你用的Compose插件版本是不是真的偏低：

docker compose version

如果显示的版本是v2.20.x及更早，那基本就是版本不兼容的问题，必须升级。

2. 升级Compose插件到匹配版本

因为我用的是Docker Engine 29.0.0，建议升级到和Docker Engine大版本对应的Compose版本（比如v2.29.x以上）。在Debian 12上可以这样操作：

• 先卸载系统apt可能安装的旧版Compose插件：

  sudo apt remove -y docker-compose-plugin
  

• 然后通过已配置的Docker官方apt源重新安装最新的匹配版本：

  sudo apt update && sudo apt install -y docker-compose-plugin
  

3. 验证升级结果

升级完成后再查一次版本：

docker compose version

如果版本显示是v2.29.x及以上，再跑docker compose ps试试，应该就不会再报API版本错误了。

4. 临时应急方案（不推荐长期使用）

如果暂时没法升级Compose，也可以把API版本环境变量设为默认生效：

• 仅当前终端会话生效：

  export DOCKER_API_VERSION=1.52
  

• 让所有用户永久生效：

  echo 'DOCKER_API_VERSION=1.52' | sudo tee /etc/profile.d/docker-api-version.sh
  source /etc/profile.d/docker-api-version.sh
  

  不过这只是权宜之计，长期来看还是得让Compose版本和Docker Engine匹配，不然以后用其他Compose命令可能还会出问题。

最终验证 #

我自己升级完Compose之后，docker compose ps就能正常返回结果了，不用再手动加环境变量，问题完美解决！