主题

srebro2026-09-04

Docker Compose 与 docker-compose 区别说明 ​

文档更新参考：Docker 官方文档（2026 年 8 月），当前 Compose 最新稳定版为 v5.5.0。

1. 一句话区分 ​

写法本质状态
docker compose（空格）Docker CLI 插件，Go 实现当前标准，持续维护
docker-compose（连字符）独立 Python 二进制（V1）已弃用，不再维护

很多人说的「Docker Compose」通常指 V2/V5 插件版（docker compose）；而 docker-compose 是旧版 V1 的命令名。两者名字相近，但安装方式、实现语言和生命周期完全不同。

2. 历史与演进 ​

2.1 Compose V1 — docker-compose ​

  • 发布时间：2014 年
  • 实现语言：Python
  • 调用方式：独立命令 docker-compose
  • 安装形态：单独下载的二进制，或通过 pip install docker-compose 安装
  • Compose 文件：常在 compose.yaml / docker-compose.yml 顶部写 version: "3.8" 等字段，表示文件格式版本
  • 现状：Docker 已于 2023 年停止维护；V1 在 2024 年 5 月 达到生命周期终点（EOL），不应再用于生产或新项目

2.2 Compose V2 — docker compose ​

  • 发布时间：2020 年宣布，逐步取代 V1
  • 实现语言：Go
  • 调用方式：作为 Docker CLI 插件，命令为 docker compose（子命令，不是独立程序名）
  • 安装形态：插件二进制 docker-compose 放在 CLI 插件目录，由 docker 主程序加载
  • Compose 文件：忽略顶层 version 字段；推荐使用 compose.yaml 命名
  • 优势：与 Docker Engine / BuildKit 深度集成，性能更好，支持 profiles、include、Watch 等新特性

2.3 Compose V5（2025 年起） ​

  • 调用方式不变：仍是 docker compose
  • 与 V2 功能等价，主要增量是官方 Compose Go SDK
  • GitHub 发布标签现为 v5.x.x（例如 v5.5.0），安装路径与 V2 插件完全相同

3. 核心差异对照表 ​

维度docker-compose（V1）docker compose（V2/V5）
命令形式独立命令，带连字符Docker 子命令，空格分隔
实现PythonGo
分发方式独立包 / pipDocker 插件或系统包 docker-compose-plugin
与 Docker CLI外挂工具，自行调用 Docker API原生 CLI 插件
version 字段需要/常用可省略，会被忽略
BuildKit支持有限原生更好支持
profiles / include / watch不支持或很弱支持
Docker Desktop旧版可能自带 V1现代版本自带 V2/V5
维护状态EOL，勿用活跃维护

4. 插件架构：为什么二进制叫 docker-compose 却要用 docker compose 调用？ ​

Compose V2/V5 不是传统意义上的「全局 docker-compose 可执行文件」，而是 Docker CLI 插件：

用户输入: docker compose up
         │
         ▼
    Docker CLI (docker)
         │
         │  在插件目录查找名为 docker-compose 的二进制
         ▼
    ~/.docker/cli-plugins/docker-compose   （当前用户）
    或 /usr/local/lib/docker/cli-plugins/docker-compose （全系统）
         │
         ▼
    插件执行 compose 子命令（up、down、build…）

插件目录搜索顺序（简化）：

  1. ~/.docker/cli-plugins/
  2. /usr/local/lib/docker/cli-plugins/
  3. /usr/lib/docker/cli-plugins/（部分发行版）

因此：

  • 文件名必须是 docker-compose（插件命名规则）
  • 用户应使用 docker compose（空格）调用
  • 若系统上还存在旧的 /usr/local/bin/docker-compose（V1），可能与插件混淆，建议卸载旧版

5. 命令与 Compose 文件迁移 ​

5.1 命令替换（最常见迁移） ​

bash
# 旧（V1）
docker-compose up -d
docker-compose down
docker-compose build

# 新（V2/V5）
docker compose up -d
docker compose down
docker compose build

脚本、CI、Makefile 中通常只需把 docker-compose 替换为 docker compose。

5.2 Compose 文件 ​

yaml
# 旧写法（V1 时代常见，V2/V5 中可删除）
version: "3.8"

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
yaml
# 推荐写法（V2/V5）
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

5.3 兼容旧脚本（可选，不推荐长期使用） ​

若暂时无法改脚本，可为插件创建符号链接，使 docker-compose 指向插件二进制：

bash
sudo ln -s /usr/local/lib/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose

路径需与实际插件安装位置一致。长期仍应迁移到 docker compose。

6. 最新 docker-compose 二进制部署方式（Compose V2/V5 插件） ​

以下均为 插件版 部署，不是 V1 独立 Python 版。部署完成后使用 docker compose version 验证。

前提：已安装 Docker Engine 20.10+ 及 Docker CLI。

6.1 方式一：系统包管理器（推荐） ​

自动更新、与发行版集成，生产环境首选。

Debian / Ubuntu：

bash
# 需先配置 Docker 官方 apt 仓库
sudo apt-get update
sudo apt-get install docker-compose-plugin

RHEL / CentOS / Fedora 等 RPM 系：

bash
sudo yum update
sudo yum install docker-compose-plugin

验证：

bash
docker compose version
# 示例输出：Docker Compose version v5.5.0

6.2 方式二：手动下载 GitHub 二进制（插件手动安装） ​

适合无法使用官方仓库、需要指定版本、或仅给当前用户安装的场景。

注意：手动安装不会自动更新，需自行跟进安全发布。

仅当前用户 ​

bash
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p "$DOCKER_CONFIG/cli-plugins"

# 将 v5.5.0 替换为所需版本；x86_64 替换为对应架构
curl -SL "https://github.com/docker/compose/releases/download/v5.5.0/docker-compose-linux-x86_64" \
  -o "$DOCKER_CONFIG/cli-plugins/docker-compose"

chmod +x "$DOCKER_CONFIG/cli-plugins/docker-compose"
docker compose version

全系统所有用户 ​

bash
sudo mkdir -p /usr/local/lib/docker/cli-plugins

curl -SL "https://github.com/docker/compose/releases/download/v5.5.0/docker-compose-linux-x86_64" \
  -o /usr/local/lib/docker/cli-plugins/docker-compose

sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
docker compose version

常见架构与文件名后缀 ​

平台文件名示例
Linux x86_64docker-compose-linux-x86_64
Linux aarch64 / ARM64docker-compose-linux-aarch64
Linux armv7docker-compose-linux-armv7
macOS Apple Silicondocker-compose-darwin-aarch64
macOS Inteldocker-compose-darwin-x86_64
Windows x86_64docker-compose-windows-x86_64.exe

完整列表与校验文件见：docker/compose Releases。

7. 参考链接 ​

最近更新