安装 docker compose v2版 笔记250731
简述
v2版是插件形式
确认系统要求, 已安装 Docker Engine(版本 20.10.5 或更高)
安装方式可分为
-
apt 或 yum 安装 (能自动升级)
apt install docker-compose-plugin
yum install docker-compose-plugin
-
手动二进制文件安装 (需手动升级): 下载二进制文件放入特定的
docker/cli-plugins
文件夹中- 下载页面: https://github.com/docker/compose/releases
- 用户级 安装放入用户文件夹中的
$HOME/.docker/cli-plugins
=~/.docker/cli-plugins
如/root/.docker/cli-plugins
- 系统级 安装放入系统文件夹中, 以下选其一
/usr/local/lib/docker/cli-plugins
/usr/local/libexec/docker/cli-plugins
/usr/lib/docker/cli-plugins
/usr/libexec/docker/cli-plugins
通过手动安装二进制文件的方式
下载页面: https://github.com/docker/compose/releases
用户级手动安装二进制文件
-
创建 Docker CLI 插件目录(如果不存在):
bashmkdir -p ~/.docker/cli-plugins/
-
下载 Docker Compose 二进制文件:
bash# 适用于 x86_64 系统 curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose # 适用于 ARM64 系统(如树莓派) # curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-aarch64 -o ~/.docker/cli-plugins/docker-compose
-
授予执行权限:
bashchmod +x ~/.docker/cli-plugins/docker-compose
-
验证安装:
bashdocker compose version
合成一步
bash
# 1. 创建插件目录
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
# 2. 下载最新版二进制文件(替换版本号)
# 查看最新版本:https://github.com/docker/compose/releases
COMPOSE_VERSION=v2.39.1 # 替换为最新版本
ARCH=$(uname -m) # 自动检测架构
curl -SL "https://github.com/docker/compose/releases/download/$COMPOSE_VERSION/docker-compose-linux-$ARCH" \
-o $DOCKER_CONFIG/cli-plugins/docker-compose
# 3. 赋予执行权限
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
# 4. 验证安装
docker compose version
安装最新版
bash
# 创建插件目录
mkdir -p ~/.docker/cli-plugins
# 下载最新版 V2 二进制文件
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o ~/.docker/cli-plugins/docker-compose
# 添加执行权限
chmod +x ~/.docker/cli-plugins/docker-compose
# 验证安装
docker compose version
系统级手动安装二进制文件
bash
# 1. 创建插件目录
DOCKER_COMPOSE_FolderPath='/usr/local/lib/docker/cli-plugins'
#DOCKER_COMPOSE_FolderPath='/usr/local/libexec/docker/cli-plugins'
#DOCKER_COMPOSE_FolderPath='/usr/lib/docker/cli-plugins'
#DOCKER_COMPOSE_FolderPath='/usr/libexec/docker/cli-plugins'
mkdir -p $DOCKER_COMPOSE_FolderPath
# 2. 下载最新版二进制文件(替换版本号)
# 查看最新版本:https://github.com/docker/compose/releases
COMPOSE_VERSION=v2.39.1 # 替换为最新版本
ARCH=$(uname -m) # 自动检测架构
curl -SL "https://github.com/docker/compose/releases/download/$COMPOSE_VERSION/docker-compose-linux-$ARCH" \
-o $DOCKER_COMPOSE_FolderPath/docker-compose
# 3. 赋予执行权限
chmod +x $DOCKER_COMPOSE_FolderPath/docker-compose
# 4. 验证安装
docker compose version
安装最新版
bash
# 创建插件目录 以下四选一
mkdir -p '/usr/local/lib/docker/cli-plugins' && cd $_
#mkdir -p '/usr/local/libexec/docker/cli-plugins' && cd $_
#mkdir -p '/usr/lib/docker/cli-plugins' && cd $_
#mkdir -p '/usr/libexec/docker/cli-plugins' && cd $_
# 下载最新版 V2 二进制文件
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o docker-compose
# 添加执行权限
chmod +x docker-compose
# 验证安装
docker compose version
通过 Docker 官方仓库安装(apt , dnf , yum)
bash
# Ubuntu/Debian 系统
sudo apt-get update
sudo apt-get install docker-compose-plugin
# CentOS/RHEL/Fedora 系统
sudo yum update
sudo yum install docker-compose-plugin
通过 Docker 官方仓库安装(适用于 Debian/Ubuntu)
-
添加 Docker 仓库(如果已安装 Docker Engine,可跳过):
bashsudo apt-get update sudo apt-get install ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
-
安装 Docker Compose 插件:
bashsudo apt-get update sudo apt-get install docker-compose-plugin
-
验证安装:
bashdocker compose version
卸载旧版 docker-compose
(可选)
如果已安装旧版(Python 编写的 docker-compose v1
),建议卸载以避免冲突:
bash
# 卸载通过 Pip 安装的旧版
sudo pip uninstall docker-compose
# 或卸载通过 apt 安装的旧版
sudo apt remove docker-compose
使用 Docker Compose v2
-
新命令格式 (注意空格):
bashdocker compose [COMMAND] # 如 docker compose up
-
兼容原有
docker-compose.yml
文件。
常见问题
-
权限错误 :确保当前用户属于
docker
用户组:bashsudo usermod -aG docker $USER newgrp docker # 刷新组权限
-
命令未找到:
- 检查
~/.docker/cli-plugins/
目录是否存在且包含docker-compose
文件。 - 确保已正确设置执行权限(
chmod +x
)。
- 检查
-
版本冲突 :彻底卸载旧版
docker-compose
。
1️⃣ 参考 1 翻译官方文档: Install the Docker Compose plugin 安装 docker compose 插件
Install the Docker Compose plugin 原文
Install the Docker Compose plugin
This page contains instructions on how to install the Docker Compose plugin on Linux from the command line.
To install the Docker Compose plugin on Linux, you can either:
- [Set up Docker's repository on your Linux system](#Set up Docker's repository on your Linux system "#install-using-the-repository").
- [Install manually](#Install manually "#install-the-plugin-manually").
!NOTE
These instructions assume you already have Docker Engine and Docker CLI installed and now want to install the Docker Compose plugin.
Install using the repository
-
Set up the repository. Find distribution-specific instructions in:
Ubuntu | CentOS | Debian | Raspberry Pi OS | Fedora | RHEL | SLES.
-
Update the package index, and install the latest version of Docker Compose:
-
For Ubuntu and Debian, run:
console$ sudo apt-get update $ sudo apt-get install docker-compose-plugin
-
For RPM-based distributions, run:
console$ sudo yum update $ sudo yum install docker-compose-plugin
-
-
Verify that Docker Compose is installed correctly by checking the version.
console$ docker compose version
Update Docker Compose
To update the Docker Compose plugin, run the following commands:
-
For Ubuntu and Debian, run:
console$ sudo apt-get update $ sudo apt-get install docker-compose-plugin
-
For RPM-based distributions, run:
console$ sudo yum update $ sudo yum install docker-compose-plugin
Install the plugin manually
!WARNING
Manual installations don't auto-update. For ease of maintenance, use the Docker repository method.
-
To download and install the Docker Compose CLI plugin, run:
console$ DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker} $ mkdir -p $DOCKER_CONFIG/cli-plugins $ curl -SL https://github.com/docker/compose/releases/download/{{% param "compose_version" %}}/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
This command downloads and installs the latest release of Docker Compose for the active user under
$HOME
directory.To install:
- Docker Compose for all users on your system, replace
~/.docker/cli-plugins
with/usr/local/lib/docker/cli-plugins
. - A different version of Compose, substitute
{{% param "compose_version" %}}
with the version of Compose you want to use. - For a different architecture, substitute
x86_64
with the architecture you want.
- Docker Compose for all users on your system, replace
-
Apply executable permissions to the binary:
console$ chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
or, if you chose to install Compose for all users:
console$ sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
-
Test the installation.
console$ docker compose version
What's next?
Install the Docker Compose plugin 翻译1
Docker Compose 插件安装指南 本文档提供 Linux 系统命令行安装 Docker Compose 插件的完整指引。
!注意
本指南默认您已安装 Docker Engine 和 Docker CLI,现需补充安装 Docker Compose 插件。
一、通过软件仓库安装(推荐) 1. 配置 Docker 软件仓库 根据发行版选择对应指南:
2. 安装最新版 Docker Compose Ubuntu/Debian 系统:
bash
sudo apt-get update
sudo apt-get install docker-compose-plugin
基于 RPM 的系统(CentOS/RHEL/Fedora):
bash
sudo yum update
sudo yum install docker-compose-plugin
3. 验证安装
bash
docker compose version
4. 升级方法 重复执行对应系统的安装命令即可升级至最新版本:
bash
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install docker-compose-plugin
# RPM 系统
sudo yum update && sudo yum install docker-compose-plugin
二、手动安装插件
!警告
手动安装无法自动更新!建议优先使用仓库安装方式以简化维护。
1. 下载并安装插件
bash
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/v2.39.1/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
自定义选项:
场景 | 操作方式 |
---|---|
为所有用户安装 | 将 ~/.docker/cli-plugins 替换为 /usr/local/lib/docker/cli-plugins |
安装特定版本 | 将链接中的 v2.39.1 替换为目标版本号 |
其他 CPU 架构 | 将 x86_64 改为目标架构(如 aarch64 ) |
2. 添加执行权限 当前用户安装:
bash
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
系统级安装:
bash
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
3. 验证安装
bash
docker compose version
✅ 输出示例:Docker Compose version v2.39.1
后续步骤
关键说明:
- 仓库安装自动处理依赖和更新
- 手动安装需定期检查 GitHub 发布页 获取更新
- 使用
docker compose
(V2 新版命令)而非旧版docker-compose
Install the Docker Compose plugin 翻译2
安装 Docker Compose 插件
本文档提供在 Linux 命令行环境下安装 Docker Compose 插件的详细指南。
安装方式选择:
!注意
本指南假设您已安装 Docker Engine 和 Docker CLI,现在仅需安装 Docker Compose 插件。
通过软件仓库安装
-
设置软件仓库
各发行版配置指南:
Ubuntu |
CentOS |
Debian |
树莓派 OS |
Fedora |
RHEL |
SLES -
安装最新版本
-
Ubuntu/Debian 系统:
console$ sudo apt-get update $ sudo apt-get install docker-compose-plugin
-
RPM 系发行版(CentOS/RHEL/Fedora):
console$ sudo yum update $ sudo yum install docker-compose-plugin
-
-
验证安装
console$ docker compose version
更新 Docker Compose 执行对应系统的安装命令即可更新:
-
Ubuntu/Debian:
console$ sudo apt-get update $ sudo apt-get install docker-compose-plugin
-
RPM 系发行版:
console$ sudo yum update $ sudo yum install docker-compose-plugin
手动安装
!警告
手动安装不支持自动更新。为便于维护,建议使用软件仓库安装方式。
-
下载并安装插件
console$ DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker} $ mkdir -p $DOCKER_CONFIG/cli-plugins $ curl -SL https://github.com/docker/compose/releases/download/{{% param "compose_version" %}}/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
- 全局安装 :将
~/.docker/cli-plugins
替换为/usr/local/lib/docker/cli-plugins
- 指定版本 :替换
{{% param "compose_version" %}}
为目标版本号 - 其他架构 :替换
x86_64
为 目标架构
- 全局安装 :将
-
授予执行权限
-
当前用户安装:
console$ chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
-
全局安装:
console$ sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
-
-
验证安装
console$ docker compose version
后续步骤
术语对照表
英文术语 | 中文翻译 |
---|---|
CLI plugin | CLI 插件 |
RPM-based distributions | RPM 系发行版 |
active user | 当前用户 |
executable permissions | 执行权限 |
maintainability | 可维护性 |
2️⃣ 参考 2 翻译官方文档 Install using the repository 用仓库安装
Install using the repository 原文
Install using the repository
-
Set up the repository. Find distribution-specific instructions in:
Ubuntu | CentOS | Debian | Raspberry Pi OS | Fedora | RHEL | SLES.
-
Update the package index, and install the latest version of Docker Compose:
-
For Ubuntu and Debian, run:
console$ sudo apt-get update $ sudo apt-get install docker-compose-plugin
-
For RPM-based distributions, run:
console$ sudo yum update $ sudo yum install docker-compose-plugin
-
-
Verify that Docker Compose is installed correctly by checking the version.
console$ docker compose version
Install using the repository 翻译
通过软件仓库安装 Docker Compose(官方推荐方式)
- 设置软件仓库 根据您的 Linux 发行版选择对应的设置指南:
- 安装最新版 Docker Compose 更新软件包索引并安装 Docker Compose 插件:
Ubuntu/Debian 系统:
bash
sudo apt-get update
sudo apt-get install docker-compose-plugin
基于 RPM 的系统 (CentOS/RHEL/Fedora):
bash
sudo yum update
sudo yum install docker-compose-plugin
- 验证安装 检查 Docker Compose 版本确认安装成功:
bash
docker compose version
更新 Docker Compose 保持最新版本的升级方法:
Ubuntu/Debian 系统:
bash
sudo apt-get update
sudo apt-get install docker-compose-plugin
基于 RPM 的系统 (CentOS/RHEL/Fedora):
bash
sudo yum update
sudo yum install docker-compose-plugin
关键说明:
- ✅ 此方法自动处理依赖关系和后续更新
- 🔄 每次执行安装命令会自动升级到最新版本
- 📦 安装的插件名称为
docker-compose-plugin
- 🌐 确保系统能正常访问 Docker 官方仓库
Install using the repository 翻译2
通过软件仓库安装
-
设置软件仓库
各发行版专属配置指南:
Ubuntu |
CentOS |
Debian |
树莓派 OS |
Fedora |
RHEL |
SLES -
安装最新版本
-
Ubuntu/Debian 系统 :
console$ sudo apt-get update $ sudo apt-get install docker-compose-plugin
-
基于 RPM 的发行版 (CentOS/RHEL/Fedora):
console$ sudo yum update $ sudo yum install docker-compose-plugin
-
-
验证安装
console$ docker compose version
注:执行验证命令后,终端将显示类似
Docker Compose version v2.24.7
的版本信息,表明安装成功。
Install using the repository 翻译3
通过软件仓库安装(推荐方式)
- 配置软件仓库 根据您的 Linux 发行版选择对应配置指南:
- 安装最新版 Docker Compose Ubuntu/Debian 系统:
bash
sudo apt-get update
sudo apt-get install docker-compose-plugin
基于 RPM 的系统(CentOS/RHEL/Fedora):
bash
sudo yum update
sudo yum install docker-compose-plugin
- 验证安装
bash
docker compose version
✅ 成功安装将显示版本号,例如:Docker Compose version v2.39.1
关键说明:
- 🔄 此方法自动处理更新,安装后可通过系统包管理器升级
- 📦 安装的是
docker-compose-plugin
官方插件包- 🌐 需确保系统能访问 Docker 官方软件源
- 💻 验证命令使用新版格式
docker compose
(非旧版docker-compose
)
3️⃣ 参考 3 翻译官方文档 Install the plugin manually 手动安装 Docker Compose 插件
Install the plugin manually 原文
!WARNING
Manual installations don't auto-update. For ease of maintenance, use the Docker repository method.
-
To download and install the Docker Compose CLI plugin, run:
console$ DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker} $ mkdir -p $DOCKER_CONFIG/cli-plugins $ curl -SL https://github.com/docker/compose/releases/download/{{% param "compose_version" %}}/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
This command downloads and installs the latest release of Docker Compose for the active user under
$HOME
directory.To install:
- Docker Compose for all users on your system, replace
~/.docker/cli-plugins
with/usr/local/lib/docker/cli-plugins
. - A different version of Compose, substitute
{{% param "compose_version" %}}
with the version of Compose you want to use. - For a different architecture, substitute
x86_64
with the architecture you want.
- Docker Compose for all users on your system, replace
-
Apply executable permissions to the binary:
console$ chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
or, if you chose to install Compose for all users:
console$ sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
-
Test the installation.
console$ docker compose version
Install the plugin manually 翻译
手动安装插件
!警告
手动安装无法自动更新! 为简化维护流程,强烈建议优先使用 [Docker 仓库安装方式](#Docker 仓库安装方式 "#")。
1. 下载并安装插件
bash
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/v2.39.1/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
此命令将为当前用户下载最新版 Docker Compose 到 $HOME
目录。
自定义安装选项:
场景 | 操作方式 |
---|---|
为所有用户安装 | 将 ~/.docker/cli-plugins 替换为 /usr/local/lib/docker/cli-plugins |
安装特定版本 | 将链接中的 v2.39.1 替换为目标版本号 |
其他 CPU 架构 | 将 x86_64 改为目标架构(如 aarch64 ) |
2. 添加执行权限 当前用户安装:
bash
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
系统级安装:
bash
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
3. 验证安装
bash
docker compose version
✅ 成功输出示例:Docker Compose version v2.39.1
关键说明:
- 此方式需定期手动检查 GitHub 发布页 获取更新
- 升级时需重复下载步骤覆盖旧文件
- 变量
{{% param "compose_version" %}}
需替换为具体版本号(如v2.39.1
)- 完整架构列表参见:官方发布页面
Install the plugin manually 翻译2
手动安装插件
!警告
手动安装不支持自动更新。为便于维护,强烈推荐使用 [Docker 软件仓库安装方式](#强烈推荐使用 Docker 软件仓库安装方式 "#%E9%80%9A%E8%BF%87%E8%BD%AF%E4%BB%B6%E4%BB%93%E5%BA%93%E5%AE%89%E8%A3%85")。
-
下载并安装 CLI 插件
bash$ DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker} $ mkdir -p $DOCKER_CONFIG/cli-plugins $ curl -SL https://github.com/docker/compose/releases/download/{{% param "compose_version" %}}/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
此命令将为当前用户下载最新版 Docker Compose 到
$HOME
目录定制选项:
- 全局安装 :将
~/.docker/cli-plugins
替换为/usr/local/lib/docker/cli-plugins
- 指定版本 :将
{{% param "compose_version" %}}
替换为目标版本(如v2.24.7
) - 其他架构 :将
x86_64
替换为 支持架构(如aarch64
)
- 全局安装 :将
-
授予执行权限
-
当前用户安装 :
bash$ chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
-
全局安装 :
bash$ sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
-
-
验证安装
bash$ docker compose version
成功安装将显示版本信息(如
Docker Compose version v2.24.7
)
关键参数说明
参数 | 作用 |
---|---|
$DOCKER_CONFIG |
自动定位 Docker 配置目录 |
mkdir -p |
递归创建目录(不存在时自动建立) |
curl -SL |
支持重定向的静默下载 |
chmod +x |
添加可执行权限 |
{{% param ... %}} |
需替换为具体版本号的实际值 |
Install the plugin manually 翻译3
以下是对 Docker Compose 手动安装插件 部分的专业中文翻译:
手动安装插件
警告
手动安装不会自动更新。为便于维护,建议使用 Docker 软件仓库安装方式。
执行以下命令下载并安装 Docker Compose CLI 插件:
bash
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/v2.39.1/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
此命令将为当前用户下载并安装最新版 Docker Compose(安装到 $HOME
目录)。
安装选项调整:
- 为系统所有用户安装
将~/.docker/cli-plugins
替换为/usr/local/lib/docker/cli-plugins
- 安装特定版本
将 URL 中的v2.39.1
替换为目标版本号 - 安装其他架构版本
将x86_64
替换为目标架构(如aarch64
)
赋予二进制文件执行权限:
-
当前用户安装:
bashchmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
-
系统级安装:
bashsudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
验证安装:
bash
docker compose version
关键说明:
- 环境变量
DOCKER_CONFIG
${DOCKER_CONFIG:-$HOME/.docker}
表示:优先使用预设的DOCKER_CONFIG
变量值,未设置则默认使用$HOME/.docker
- 目录结构
CLI 插件必须安装在cli-plugins
子目录中 - 权限要求
chmod +x
是必要步骤,否则无法执行命令 - 版本控制
手动安装需自行跟踪GitHub 发布页获取更新 - 架构支持
常见架构标识:
x86_64
(Intel/AMD 64位) |aarch64
(ARM 64位) |armv7
(ARMv7) |ppc64le
(PowerPC)
4️⃣ 参考 4 翻译官方文档: Migrate from Docker Compose v1 to v2 (从 Docker Compose v1 迁移至 v2)
Migrate from Docker Compose v1 to v2 原文
Migrate from Docker Compose v1 to v2
From July 2023, Compose v1 stopped receiving updates. It's also no longer available in new releases of Docker Desktop.
Compose v2, which was first released in 2020, is included with all currently supported versions of Docker Desktop. It offers an improved CLI experience, improved build performance with BuildKit, and continued new-feature development.
How do I switch to Compose v2?
The easiest and recommended way is to make sure you have the latest version of Docker Desktop, which bundles the Docker Engine and Docker CLI platform including Compose v2.
With Docker Desktop, Compose v2 is always accessible as docker compose
.
For manual installs on Linux, you can get Compose v2 by either:
- Using Docker's repository (recommended)
- Downloading and installing manually
What are the differences between Compose v1 and Compose v2?
docker-compose
vs docker compose
Unlike Compose v1, Compose v2 integrates into the Docker CLI platform and the recommended command-line syntax is docker compose
.
The Docker CLI platform provides a consistent and predictable set of options and flags, such as the DOCKER_HOST
environment variable or the --context
command-line flag.
This change lets you use all of the shared flags on the root docker
command. For example, docker --log-level=debug --tls compose up
enables debug logging from the Docker Engine as well as ensuring that TLS is used for the connection.
!TIP
Update scripts to use Compose v2 by replacing the hyphen (
-
) with a space, usingdocker compose
instead ofdocker-compose
.
Service container names
Compose generates container names based on the project name, service name, and scale/replica count.
In Compose v1, an underscore (_
) was used as the word separator. In Compose v2, a hyphen (-
) is used as the word separator.
Underscores aren't valid characters in DNS hostnames. By using a hyphen instead, Compose v2 ensures service containers can be accessed over the network via consistent, predictable hostnames.
For example, running the Compose command -p myproject up --scale=1 svc
results in a container named myproject_svc_1
with Compose v1 and a container named myproject-svc-1
with Compose v2.
!TIP
In Compose v2, the global
--compatibility
flag orCOMPOSE_COMPATIBILITY
environment variable preserves the Compose v1 behavior to use underscores (_
) as the word separator. As this option must be specified for every Compose v2 command run, it's recommended that you only use this as a temporary measure while transitioning to Compose v2.
Command-line flags and subcommands
Compose v2 supports almost all Compose V1 flags and subcommands, so in most cases, it can be used as a drop-in replacement in scripts.
Unsupported in v2
The following were deprecated in Compose v1 and aren't supported in Compose v2:
docker-compose scale
. Usedocker compose up --scale
instead.docker-compose rm --all
Different in v2
The following behave differently between Compose v1 and v2:
Compose v1 | Compose v2 | |
---|---|---|
--compatibility |
Deprecated. Migrates YAML fields based on legacy schema version. | Uses _ as word separator for container names instead of - to match v1. |
ps --filter KEY-VALUE |
Undocumented. Allows filtering by arbitrary service properties. | Only allows filtering by specific properties, e.g. --filter=status=running . |
Environment variables
Environment variable behavior in Compose v1 wasn't formally documented and behaved inconsistently in some edge cases.
For Compose v2, the Environment variables section covers both precedence as well as .env
file interpolation and includes many examples covering tricky situations such as escaping nested quotes.
Check if:
- Your project uses multiple levels of environment variable overrides, for example
.env
file and--env
CLI flags. - Any
.env
file values have escape sequences or nested quotes. - Any
.env
file values contain literal$
signs in them. This is common with PHP projects. - Any variable values use advanced expansion syntax, for example
${VAR:?error}
.
!TIP
Run
docker compose config
on the project to preview the configuration after Compose v2 has performed interpolation to verify that values appear as expected.Maintaining backwards compatibility with Compose v1 is typically achievable by ensuring that literal values (no interpolation) are single-quoted and values that should have interpolation applied are double-quoted.
What does this mean for my projects that use Compose v1?
For most projects, switching to Compose v2 requires no changes to the Compose YAML or your development workflow.
It's recommended that you adapt to the new preferred way of running Compose v2, which is to use docker compose
instead of docker-compose
. This provides additional flexibility and removes the requirement for a docker-compose
compatibility alias.
However, Docker Desktop continues to support a docker-compose
alias to redirect commands to docker compose
for convenience and improved compatibility with third-party tools and scripts.
Is there anything else I need to know before I switch?
Migrating running projects
In both v1 and v2, running up on a Compose project recreates service containers as needed. It compares the actual state in the Docker Engine to the resolved project configuration, which includes the Compose YAML, environment variables, and command-line flags.
Because Compose v1 and v2 [name service containers differently](#name service containers differently "#service-container-names"), running up
using v2 the first time on a project with running services originally launched by v1, results in service containers being recreated with updated names.
Note that even if --compatibility
flag is used to preserve the v1 naming style, Compose still needs to recreate service containers originally launched by v1 the first time up
is run by v2 to migrate the internal state.
Using Compose v2 with Docker-in-Docker
Compose v2 is now included in the Docker official image on Docker Hub.
Additionally, a new docker/compose-bin image on Docker Hub packages the latest version of Compose v2 for use in multi-stage builds.
Can I still use Compose v1 if I want to?
Yes. You can still download and install Compose v1 packages, but you won't get support from Docker if anything breaks.
!WARNING
The final Compose v1 release, version 1.29.2, was May 10, 2021. These packages haven't received any security updates since then. Use at your own risk.
Additional Resources
Migrate from Docker Compose v1 to v2 翻译
从 Docker Compose v1 迁移至 v2 指南
2023年7月起 ,Compose v1 已停止更新,且不再包含在新版 Docker Desktop 中。
Compose v2(2020年首发)随所有当前支持的 Docker Desktop 版本提供,具备以下优势:
- 🚀 优化的 CLI 体验
- ⚡️ 基于 BuildKit 的构建性能提升
- 🌟 持续的新功能开发
如何切换至 Compose v2? 推荐方案:安装最新版 Docker Desktop
- 自动集成 Docker Engine、Docker CLI 及 Compose v2
- 命令格式:
docker compose
(注意空格替代连字符)
Linux 手动安装方案:
- 通过 Docker 仓库安装(推荐)
- 手动下载安装
v1 与 v2 的核心差异 1. 命令格式变更
v1 | v2 | |
---|---|---|
命令 | docker-compose |
docker compose |
优势 | - | 支持 Docker CLI 全局参数(如 --context , DOCKER_HOST ) 例:docker --log-level=debug compose up |
!TIP
迁移脚本 :将所有
docker-compose
替换为docker compose
2. 容器命名规则
v1 示例 | v2 示例 | 原因 | |
---|---|---|---|
分隔符 | myproject_svc_1 |
myproject-svc-1 |
下划线 _ 不符合 DNS 主机名规范 |
兼容方案 | - | 启动时添加全局参数: --compatibility 或 COMPOSE_COMPATIBILITY=true (临时过渡使用) |
3. 命令参数变更
命令 | v1 状态 | v2 替代方案 |
---|---|---|
scale |
❌ 已弃用 | docker compose up --scale |
rm --all |
❌ 不支持 | 无直接替代 |
4. 环境变量处理优化 v2 正式规范了环境变量的:
!TIP
验证配置 :运行
docker compose config
预览解析后的配置
迁移影响与注意事项 对现有项目的影响
- 多数项目 无需修改
compose.yaml
- 需将脚本中的
docker-compose
改为docker compose
- Docker Desktop 仍保留
docker-compose
别名(兼容第三方工具)
首次迁移运行警告 ⚠️ 若对 v1 启动的容器 首次运行 docker compose up
:
- 容器将按 v2 规则重建(因命名规则变更)
- 即使使用
--compatibility
参数也会触发重建(需迁移内部状态)
特殊场景支持
场景 | 方案 |
---|---|
Docker-in-Docker | 使用 Docker 官方镜像(含 v2) |
多阶段构建 | 使用 docker/compose-bin 镜像 |
v1 的后续支持
项目 | 状态 |
---|---|
最终版本 | v1.29.2(2021年5月发布) |
安全更新 | ❌ 已停止 |
下载渠道 | PyPI · Docker Hub · GitHub |
!WARNING
风险提示:继续使用 v1 可能面临安全漏洞,且不受 Docker 官方支持
迁移资源
Migrate from Docker Compose v1 to v2 翻译2
从 Docker Compose v1 迁移至 v2
背景说明
自 2023 年 7 月起,Compose v1 已停止更新,且不再包含于新版 Docker Desktop 中。
Compose v2(2020 年首发)已集成至所有受支持的 Docker Desktop 版本,提供:
✅ 优化的 CLI 体验
✅ 基于 BuildKit 的构建性能提升
✅ 持续的功能迭代
如何切换到 Compose v2? 推荐方案
升级至最新版 Docker Desktop,该版本已内置 Compose v2,直接使用 docker compose
命令即可。
Linux 手动迁移方案
- 通过 Docker 仓库安装(推荐)
- 手动下载安装
v1 与 v2 的核心差异 1. 命令格式变更
版本 | 命令格式 | 说明 |
---|---|---|
v1 | docker-compose |
独立命令 |
v2 | docker compose |
集成至 Docker CLI 平台,支持全局参数(如 --context 、DOCKER_HOST ) |
💡 迁移提示 :将脚本中的
docker-compose
替换为docker compose
2. 容器命名规则
版本 | 分隔符 | 示例 (-p myproject up --scale=1 svc ) |
---|---|---|
v1 | _ |
myproject_svc_1 |
v2 | - |
myproject-svc-1 |
⚠️ 兼容性选项 :
使用
--compatibility
标志或COMPOSE_COMPATIBILITY
环境变量可临时启用 v1 命名规则(下划线分隔)
3. 命令参数变更 已弃用功能
docker-compose scale
→ 改用docker compose up --scale
docker-compose rm --all
行为差异
参数 | v1 行为 | v2 行为 |
---|---|---|
--compatibility |
迁移旧版 YAML 字段 | 容器名改用 _ 分隔符 |
ps --filter KEY-VALUE |
支持任意服务属性过滤 | 仅支持特定属性(如 --filter=status=running ) |
4. 环境变量处理优化 v2 明确规范了:
- 变量优先级规则
.env
文件解析机制- 特殊字符处理(如
$
、嵌套引号)
💡 验证建议 :
执行
docker compose config
预览配置解析结果,确保变量值符合预期
迁移影响与注意事项 对现有项目的影响
- 大多数项目无需修改 YAML 文件
- 需将工作流中的命令从
docker-compose
改为docker compose
- Docker Desktop 仍保留
docker-compose
别名以兼容旧脚本
运行中项目的迁移 ⚠️ 首次切换时容器会重建
因命名规则差异,v2 首次启动由 v1 创建的项目时:
- 停止旧容器(
myproject_svc_1
格式) - 创建新容器(
myproject-svc-1
格式)
即使使用
--compatibility
标志也会触发重建
Docker-in-Docker 场景
- Docker 官方镜像 已集成 Compose v2
- 多阶段构建可使用 docker/compose-bin
关于继续使用 v1 的警告
⚠️ 强烈不建议继续使用
- 最终版本 v1.29.2 发布于 2021 年 5 月 10 日
- 不再提供安全更新
- 官方停止支持
资源链接:
术语对照表
英文术语 | 中文翻译 |
---|---|
drop-in replacement | 直接替代 |
word separator | 单词分隔符 |
environment variable precedence | 环境变量优先级 |
compatibility flag | 兼容性标志 |
Docker-in-Docker | Docker 嵌套容器方案 |
Migrate from Docker Compose v1 to v2 翻译3
以下是对 Docker Compose v1 迁移至 v2 指南的专业中文翻译:
从 Docker Compose v1 迁移到 v2
自 2023 年 7 月起,Compose v1 已停止更新。新版本的 Docker Desktop 也不再包含 v1。
Compose v2(2020 年首次发布)已集成到所有当前支持的 Docker Desktop 版本中。它提供了更优的 CLI 体验、通过 BuildKit 提升构建性能,并持续支持新功能开发。
如何切换到 Compose v2?
推荐方案 :安装最新版 Docker Desktop,该版本捆绑了包含 Compose v2 的 Docker Engine 和 Docker CLI 平台。
在 Docker Desktop 中,始终可通过 docker compose
命令使用 Compose v2。
Linux 手动安装方案:
v1 与 v2 的主要差异
命令格式:docker-compose
→ docker compose
Compose v2 已集成到 Docker CLI 平台,命令格式改为 docker compose
(带空格)。
此变更使您能使用 Docker 根命令的共享标志(如 DOCKER_HOST
环境变量或 --context
命令行标志):
bash
docker --log-level=debug --tls compose up # 同时启用调试日志和 TLS 连接
!提示\] 将脚本中的连字符(`-`)替换为空格:**`docker compose`** 替代 `docker-compose`
服务容器命名规则
版本 | 命名规则 | 示例 (-p myproject up --scale=1 svc ) |
---|---|---|
v1 | 使用下划线 _ 分隔单词 |
myproject_svc_1 |
v2 | 使用连字符 - 分隔单词 |
myproject-svc-1 |
!提示\] v2 中可通过全局标志 `--compatibility` 或环境变量 `COMPOSE_COMPATIBILITY` 保留 v1 的下划线命名规则(建议仅作为过渡期临时方案)
命令行标志与子命令 v2 支持绝大多数 v1 的 flags 和子命令,通常可直接替代旧版脚本。
v2 不再支持的功能
docker-compose scale
→ 改用docker compose up --scale
docker-compose rm --all
行为变更的功能
功能 | Compose v1 | Compose v2 |
---|---|---|
--compatibility |
根据旧 schema 迁移 YAML 字段 | 改用 _ 作为容器名单词分隔符(保持 v1 风格) |
ps --filter KEY-VALUE |
支持任意服务属性过滤(未文档化) | 仅支持特定属性过滤(如 --filter=status=running ) |
环境变量处理 v1 的环境变量行为未正式文档化,且在某些边界场景表现不一致。
v2 的环境变量文档明确了:
- 变量优先级规则
.env
文件插值机制- 特殊场景处理(如转义嵌套引号)
需重点检查:
- 多级变量覆盖(如同时使用
.env
和--env
) .env
中含转义序列或嵌套引号的值- 含字面量
$
的值(常见于 PHP 项目) - 使用高级扩展语法的变量(如
${VAR:?error}
)
!提示\] 运行 `docker compose config` 预览配置插值结果,验证是否符合预期。 保持 v1 兼容性建议:字面值用单引号,需插值的变量用双引号。
对现有 v1 项目的影响 大多数项目无需修改 Compose YAML 或工作流 。
推荐改用 docker compose
命令,这将提供额外灵活性并消除对 docker-compose
兼容性别名的依赖。
Docker Desktop 仍保留
docker-compose
别名(重定向到docker compose
)以兼容第三方工具和脚本。
迁移前的注意事项
运行中项目的迁移 当 v1 和 v2 执行 up
时,都会按需重建服务容器。但两者使用不同的容器命名规则,导致 v1 启动的容器在首次使用 v2 时会重建(获得新名称)。
即使使用
--compatibility
标志保留 v1 命名风格,首次迁移时仍需重建容器以更新内部状态。
Docker-in-Docker 场景的使用 Compose v2 现已包含在 Docker 官方镜像中。
另提供专用镜像 docker/compose-bin 用于多阶段构建。
能否继续使用 Compose v1? 可以,但存在风险:
- 仍可下载安装 v1 包,但 Docker 不再提供支持
- 最终版本 v1.29.2 发布于 2021 年 5 月 10 日,此后无安全更新
资源参考
关键迁移建议:
- 生产环境优先采用 Docker Desktop 或仓库安装的 v2
- 批量替换脚本中的
docker-compose
为docker compose
- 使用
docker compose config
验证环境变量插值 - 复杂项目首次迁移时添加
--compatibility
标志过渡 - 避免继续使用已停止维护的 v1 版本
5️⃣ 参考 5 [github 的 docker compose 的 README.md 翻译 ]
github 的 docker compose 的 README.md 原文
Table of Contents
- [Docker Compose v2](#Docker Compose v2 "#docker-compose-v2")
- [Where to get Docker Compose](#Where to get Docker Compose "#where-to-get-docker-compose")
- [Windows and macOS](#Windows and macOS "#windows-and-macos")
- Linux
- [Quick Start](#Quick Start "#quick-start")
- Contributing
- Legacy Docker Compose v2


Docker Compose is a tool for running multi-container applications on Docker defined using the Compose file format. A Compose file is used to define how one or more containers that make up your application are configured. Once you have a Compose file, you can create and start your application with a single command: docker compose up
.
Note : About Docker Swarm Docker Swarm used to rely on the legacy compose file format but did not adopted the compose specification so is missing some of the recent enhancements in the compose syntax. After acquisition by Mirantis swarm isn't maintained by Docker Inc, and as such some Docker Compose features aren't accessible to swarm users.
Where to get Docker Compose
Windows and macOS
Docker Compose is included in Docker Desktop for Windows and macOS.
Linux
You can download Docker Compose binaries from the release page on this repository.
Rename the relevant binary for your OS to docker-compose
and copy it to $HOME/.docker/cli-plugins
Or copy it into one of these folders to install it system-wide:
/usr/local/lib/docker/cli-plugins
OR/usr/local/libexec/docker/cli-plugins
/usr/lib/docker/cli-plugins
OR/usr/libexec/docker/cli-plugins
(might require making the downloaded file executable with chmod +x
)
Quick Start
Using Docker Compose is a three-step process:
- Define your app's environment with a
Dockerfile
so it can be reproduced anywhere. - Define the services that make up your app in
compose.yaml
so they can be run together in an isolated environment. - Lastly, run
docker compose up
and Compose will start and run your entire app.
A Compose file looks like this:
yaml
services:
web:
build: .
ports:
- "5000:5000"
volumes:
- .:/code
redis:
image: redis
Contributing
Want to help develop Docker Compose? Check out our contributing documentation.
If you find an issue, please report it on the issue tracker.
Legacy
The Python version of Compose is available under the v1
branch.
github 的 docker compose 的 README.md 翻译
Docker Compose v2 中文文档
目录
- [Docker Compose v2](#Docker Compose v2 "#docker-compose-v2")
- [获取 Docker Compose](#获取 Docker Compose "#%E8%8E%B7%E5%8F%96-docker-compose")
- [Windows 和 macOS](#Windows 和 macOS "#windows-%E5%92%8C-macos")
- Linux
- 快速入门
- 参与贡献
- 旧版支持
Docker Compose v2
Docker Compose 是基于 Compose 文件格式 运行多容器应用的工具。通过 Compose 文件定义应用的容器配置后,只需一条命令即可启动完整应用:
bash
docker compose up
注意:关于 Docker Swarm
Docker Swarm 曾依赖旧版 Compose 格式,但未采用 Compose 规范,因此缺少最新语法特性。
自 Mirantis 收购 后,Swarm 不再由 Docker 公司维护,部分 Compose 功能对 Swarm 用户不可用。
获取 Docker Compose Windows 和 macOS Docker Compose 已内置在 Docker Desktop 中。
Linux
-
从 发布页面 下载二进制文件
-
重命名为
docker-compose
并复制到以下目录:- 用户级 :
$HOME/.docker/cli-plugins
- 系统级 :
/usr/local/lib/docker/cli-plugins
或/usr/local/libexec/docker/cli-plugins
/usr/lib/docker/cli-plugins
或/usr/libexec/docker/cli-plugins
- 用户级 :
-
添加执行权限 :
bashchmod +x /目标路径/docker-compose
快速入门 只需三步即可运行应用:
- 定义环境 :用
Dockerfile
确保环境可移植 - 配置服务 :在
compose.yaml
中定义应用服务 - 一键启动 :执行
docker compose up
示例 compose.yaml
yaml
services:
web:
build: . # 构建当前目录镜像
ports:
- "5000:5000" # 端口映射
volumes:
- .:/code # 实时同步代码
redis:
image: redis # 使用官方 Redis 镜像
参与贡献
旧版支持 Python 编写的 Compose v1 可在 v1 分支 获取(已停止更新)。
github 的 docker compose 的 README.md 翻译 2
Docker Compose v2 文档
目录
- [Docker Compose v2](#Docker Compose v2 "#docker-compose-v2")
- [获取 Docker Compose](#获取 Docker Compose "#%E8%8E%B7%E5%8F%96-docker-compose")
- [Windows 与 macOS](#Windows 与 macOS "#windows-%E4%B8%8E-macos")
- Linux
- 快速入门
- 参与贡献
- 旧版说明
Docker Compose v2
Docker Compose 是基于 Compose 文件格式 在 Docker 上运行多容器应用的工具。
通过 Compose 文件定义应用的容器配置,只需一条命令即可启动整个应用:
bash
docker compose up
注意 :关于 Docker Swarm
Docker Swarm 曾依赖旧版 Compose 文件格式,但未采用 Compose 规范,因此缺失新语法特性。
自 Mirantis 收购 后,Swarm 已非 Docker 官方维护,部分功能对 Swarm 用户不可用。
获取 Docker Compose Windows 与 macOS Docker Compose 已包含在 Docker Desktop 中,安装即用。
Linux 从 发布页面 下载二进制文件:
- 重命名为
docker-compose
- 复制到以下目录:
- 用户级 :
$HOME/.docker/cli-plugins
- 系统级 :
/usr/local/lib/docker/cli-plugins
或/usr/local/libexec/docker/cli-plugins
/usr/lib/docker/cli-plugins
或/usr/libexec/docker/cli-plugins
(可能需要执行chmod +x
添加可执行权限)
- 用户级 :
快速入门 三步启动应用:
- 定义环境 :用
Dockerfile
确保环境可复现 - 配置服务 :在
compose.yaml
中定义应用服务 - 启动应用 :执行
docker compose up
示例 compose.yaml
:
yaml
services:
web:
build: . # 构建当前目录镜像
ports:
- "5000:5000" # 端口映射
volumes:
- .:/code # 目录挂载
redis:
image: redis # 使用官方镜像
参与贡献 参与开发?查阅 贡献指南。
发现问题?提交至 问题跟踪器。
旧版说明 Python 版 Compose 请访问 v1
分支。
关键术语对照
英文术语 | 中文翻译 |
---|---|
multi-container | 多容器 |
Compose file format | Compose 文件格式 |
isolated environment | 隔离环境 |
legacy compose format | 旧版 Compose 格式 |
cli-plugins | CLI 插件目录 |
6️⃣ 参考 6 安装 docker compose v2版 多个AI回答
安装 docker compose v2版 回答1
Docker Compose v2 安装指南 以下是最简洁的 跨平台安装方案,支持 Linux/macOS/Windows(含 WSL):
通用安装命令
bash
# 创建插件目录
mkdir -p ~/.docker/cli-plugins
# 下载最新版 V2 二进制文件
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o ~/.docker/cli-plugins/docker-compose
# 添加执行权限
chmod +x ~/.docker/cli-plugins/docker-compose
# 验证安装
docker compose version
✅ 成功输出:Docker Compose version v2.x.x
系统专属方案 Linux 系统
bash
# 推荐:通过官方仓库安装(自动更新)
sudo apt-get update && sudo apt-get install docker-compose-plugin # Debian/Ubuntu
sudo yum update && sudo yum install docker-compose-plugin # CentOS/RHEL
macOS 系统
bash
# Homebrew 安装(首选)
brew install docker-compose
# 或手动安装
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-darwin-$(uname -m) -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose
Windows 系统
- 安装 Docker Desktop
- 勾选 Use Docker Compose V2(安装时默认选中)
或在 PowerShell 中执行:
powershellcurl.exe -L https://github.com/docker/compose/releases/latest/download/docker-compose-windows-x86_64.exe -o $env:USERPROFILE\.docker\cli-plugins\docker-compose.exe
安装验证
bash
# 创建测试项目
mkdir compose-test && cd compose-test
cat > compose.yaml <<EOF
services:
test:
image: alpine:latest
command: echo "Docker Compose V2 安装成功!"
EOF
# 运行测试
docker compose up
🟢 成功输出:Docker Compose V2 安装成功!
关键说明
-
安装位置:
- 用户级:
~/.docker/cli-plugins/
- 系统级:
/usr/local/lib/docker/cli-plugins/
- 用户级:
-
命令区别:
- ✅ 新版:
docker compose [命令]
- ❌ 旧版:
docker-compose [命令]
- ✅ 新版:
-
升级方法:
bashrm ~/.docker/cli-plugins/docker-compose # 重新执行安装命令
注意:
- 手动安装需定期检查 GitHub 发布页 获取更新
- 完整文档:官方安装指南
安装 docker compose v2版 回答2
以下是安装 Docker Compose v2 的完整指南,提供两种推荐方法:
方法一:通过软件仓库安装(推荐,支持自动更新)
bash
# Ubuntu/Debian 系统
sudo apt-get update
sudo apt-get install docker-compose-plugin
# CentOS/RHEL/Fedora 系统
sudo yum update
sudo yum install docker-compose-plugin
方法二:手动安装(通用方法)
bash
# 创建安装目录
mkdir -p ~/.docker/cli-plugins
# 下载最新版(自动检测架构)
ARCH=$(uname -m | sed 's/x86_64/x86_64/;s/aarch64/aarch64/;s/armv7l/armv7/')
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$ARCH -o ~/.docker/cli-plugins/docker-compose
# 授予执行权限
chmod +x ~/.docker/cli-plugins/docker-compose
验证安装
bash
docker compose version
# 成功安装会显示:Docker Compose version v2.x.x
系统级安装(所有用户可用)
bash
# 下载到系统目录
sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m | sed 's/x86_64/x86_64/;s/aarch64/aarch64/') -o /usr/local/lib/docker/cli-plugins/docker-compose
# 授予权限
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
安装后测试
bash
# 创建测试项目
mkdir compose-test && cd compose-test
echo 'services: test: image: alpine:latest command: echo "Compose v2 Installed!"' > compose.yaml
# 运行测试
docker compose up
# 成功输出会显示:compose-test-test-1 exited with code 0
重要说明
-
先决条件 :需先安装 Docker Engine
-
架构支持 :
- Intel/AMD CPU:使用
x86_64
- 苹果 M 系列/树莓派 4:使用
aarch64
- 旧款 ARM 设备:使用
armv7
- Intel/AMD CPU:使用
-
版本管理 :
bash# 查看可用版本 curl -s https://api.github.com/repos/docker/compose/releases/latest | grep tag_name # 安装特定版本(如 v2.24.7) curl -SL https://github.com/docker/compose/releases/download/v2.24.7/docker-compose-linux-$(uname -m) -o ~/.docker/cli-plugins/docker-compose
-
迁移旧版 :
bash# 卸载旧版 v1 sudo apt remove docker-compose # Ubuntu/Debian sudo pip uninstall docker-compose # Pip安装 # 更新现有脚本 sed -i 's/docker-compose/docker compose/g' your_script.sh
提示 :对于 Windows/macOS 用户,安装 Docker Desktop 即自动包含 Compose v2,无需单独安装。
安装 docker compose v2版 回答3
安装 Docker Compose V2 新版指南
方法一:通过官方仓库安装(推荐)
bash
# Ubuntu/Debian 系统
sudo apt update
sudo apt install docker-compose-plugin
# CentOS/RHEL 系统
sudo yum update
sudo yum install docker-compose-plugin
# 验证安装
docker compose version
# 应输出:Docker Compose version v2.x.x
方法二:手动安装(适用于所有 Linux)
bash
# 下载最新版(x86_64 架构)
DOCKER_DIR="${DOCKER_DIR:-$HOME/.docker}"
mkdir -p $DOCKER_DIR/cli-plugins
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 -o $DOCKER_DIR/cli-plugins/docker-compose
# 授予执行权限
chmod +x $DOCKER_DIR/cli-plugins/docker-compose
# 验证安装
docker compose version
其他架构替换方案
架构类型 | 下载链接替换部分 |
---|---|
ARM64 (树莓派) | linux-aarch64 |
Apple Silicon | darwin-aarch64 |
Intel Mac | darwin-x86_64 |
Windows | windows-x86_64.exe |
系统级安装(所有用户可用)
bash
sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo curl -SL https://github.com/docker/compose/releases/latest/download/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
配置命令别名(兼容旧版)
bash
echo "alias docker-compose='docker compose'" >> ~/.bashrc
source ~/.bashrc
升级现有版本
bash
# 仓库安装用户
sudo apt update && sudo apt install docker-compose-plugin # Ubuntu/Debian
sudo yum update && sudo yum install docker-compose-plugin # CentOS/RHEL
# 手动安装用户:重复下载步骤覆盖旧文件
验证安装成功
bash
docker compose version
# 输出示例:
# Docker Compose version v2.24.5
注意事项
-
依赖要求:需先安装 Docker Engine 20.10.10+
-
权限配置 :将用户加入 docker 组避免 sudo
bashsudo usermod -aG docker $USER newgrp docker # 立即生效
-
命令变化 :
- V1 旧命令:
docker-compose up
- V2 新命令:
docker compose up
- V1 旧命令:
推荐使用仓库安装方式,可获得自动安全更新。生产环境应使用最新稳定版,可通过 GitHub Releases 查看版本信息。
安装 docker compose v2版 回答4
以下是安装 Docker Compose V2 的完整指南,适用于各主流操作系统:
所有系统通用前提
-
确保已安装最新版 Docker Engine
bashdocker --version
若未安装:官方 Docker 安装指南
安装方法(按操作系统选择)
Linux 系统 (推荐仓库安装)
bash
# 1. 添加 Docker 官方仓库 (以 Ubuntu 为例)
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 2. 安装 Docker Compose V2
sudo apt-get update
sudo apt-get install docker-compose-plugin
# 3. 验证安装
docker compose version
# 应输出:Docker Compose version v2.x.x
Windows/macOS 系统
-
下载并安装最新版 Docker Desktop
-
安装后直接使用:
bashdocker compose version
手动安装(通用方法)
bash
# 下载二进制文件 (替换版本号和架构)
DOCKER_COMPOSE_VERSION="v2.24.5" # 从 https://github.com/docker/compose/releases 获取最新版
ARCH="x86_64" # 可选: aarch64, armv7, etc.
# 安装到当前用户
mkdir -p ~/.docker/cli-plugins
curl -SL "https://github.com/docker/compose/releases/download/${DOCKER_COMPOSE_VERSION}/docker-compose-linux-${ARCH}" -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose
# 验证
docker compose version
关键注意事项
-
命令变化:
bash# V2 使用新语法 (无连字符) docker compose up -d # ✅ 正确 docker-compose up -d # ⚠️ 旧版 V1 语法
-
卸载旧版 V1 (如已安装):
bash# Linux sudo apt remove docker-compose sudo rm /usr/local/bin/docker-compose # macOS brew uninstall docker-compose
-
自动补全 (增强体验):
bash# Linux bash 补全 sudo curl -L https://raw.githubusercontent.com/docker/compose/v2/contrib/completion/bash/docker-compose -o /etc/bash_completion.d/docker-compose
迁移项目到 V2
-
更新脚本:将所有
docker-compose
替换为docker compose
-
容器命名变更:
- V1:
project_service_1
- V2:
project-service-1
临时兼容:使用
docker compose --compatibility up
保持旧命名 - V1:
验证安装成功
bash
# 创建测试项目
mkdir compose-test && cd compose-test
echo 'services: nginx: image: nginx' > compose.yaml
# 启动服务
docker compose up -d
# 检查状态
docker compose ps
# 清理
docker compose down --rmi all
💡 提示:遇到权限问题请运行
sudo usermod -aG docker $USER
并重新登录
通过上述步骤,您将在所有主流系统上完成 Docker Compose V2 的安装和验证。
安装 docker compose v2版 回答5
以下是安装 Docker Compose v2 的完整指南:
安装 Docker Compose v2 的三种方法
方法一:通过 Docker Desktop 安装 (推荐)
bash
# 1. 下载并安装 Docker Desktop
https://www.docker.com/products/docker-desktop/
# 2. 安装后验证
docker compose version
# 应输出:Docker Compose version v2.x.x
✅ 适合 :Windows/macOS 用户
✅ 优势:自动更新、一键安装
方法二:Linux 仓库安装 (Debian/Ubuntu)
bash
# 1. 更新仓库
sudo apt-get update
# 2. 安装插件
sudo apt-get install docker-compose-plugin
# 3. 验证安装
docker compose version
方法三:手动安装 (所有 Linux 系统)
bash
# 1. 创建插件目录
mkdir -p ~/.docker/cli-plugins
# 2. 下载二进制文件 (替换版本号)
curl -SL https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-linux-$(uname -m) -o ~/.docker/cli-plugins/docker-compose
# 3. 添加执行权限
chmod +x ~/.docker/cli-plugins/docker-compose
# 4. 验证安装
docker compose version
系统级安装 (所有用户可用)
bash
# 1. 下载到系统目录
sudo curl -SL https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-linux-$(uname -m) -o /usr/local/lib/docker/cli-plugins/docker-compose
# 2. 添加执行权限
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
安装验证与测试
bash
# 检查版本
docker compose version
# 创建测试项目
mkdir compose-test && cd compose-test
echo 'services: nginx: image: nginx' > compose.yaml
# 启动服务
docker compose up -d
# 检查状态
docker compose ps
常见问题解决
-
权限错误
bashsudo usermod -aG docker $USER # 添加用户到docker组 newgrp docker # 刷新组权限
-
架构不匹配
替换下载链接中的
$(uname -m)
为实际架构:- x86_64 (Intel/AMD)
- aarch64 (ARM)
- ppc64le (PowerPC)
-
版本升级
bash# 手动安装时重新下载新版本文件 curl -SL https://github.com/docker/compose/releases/download/v2.24.6/docker-compose-linux-$(uname -m) -o ~/.docker/cli-plugins/docker-compose
💡 提示 :访问 GitHub Releases 获取最新版本号替换
v2.24.5
安装 docker compose v2版 回答6
以下是安装 Docker Compose v2 的完整指南:
安装步骤(Linux 系统)
方法一:通过软件仓库安装(推荐,支持自动更新)
bash
# 1. 更新系统包索引
sudo apt-get update # Ubuntu/Debian
# 或
sudo yum update # CentOS/RHEL
# 2. 安装 Docker Compose 插件
sudo apt-get install docker-compose-plugin # Ubuntu/Debian
# 或
sudo yum install docker-compose-plugin # CentOS/RHEL
# 3. 验证安装
docker compose version
# 应输出:Docker Compose version v2.x.x
方法二:手动安装(适合自定义需求)
bash
# 1. 创建插件目录
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
# 2. 下载最新版二进制文件(替换版本号)
# 查看最新版本:https://github.com/docker/compose/releases
COMPOSE_VERSION=v2.24.5 # 替换为最新版本
ARCH=$(uname -m) # 自动检测架构
curl -SL "https://github.com/docker/compose/releases/download/$COMPOSE_VERSION/docker-compose-linux-$ARCH" \
-o $DOCKER_CONFIG/cli-plugins/docker-compose
# 3. 赋予执行权限
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
# 4. 验证安装
docker compose version
Windows/macOS 用户 Docker Compose v2 已包含在 Docker Desktop 中:
-
下载并安装最新版 Docker Desktop
-
安装后直接在终端使用:
bashdocker compose version
安装后配置
-
迁移旧版命令:
bash# 替换所有脚本中的旧命令 sed -i 's/docker-compose/docker compose/g' your-script.sh
-
启用命令补全:
bash# Bash 用户 docker completion bash > /etc/bash_completion.d/docker-compose source ~/.bashrc # Zsh 用户 mkdir -p ~/.zsh/completion docker completion zsh > ~/.zsh/completion/_docker echo "fpath=(~/.zsh/completion \$fpath)" >> ~/.zshrc source ~/.zshrc
验证安装成功
bash
# 创建测试项目
mkdir compose-test && cd compose-test
# 创建示例 compose.yaml
cat > compose.yaml <<EOF
services:
web:
image: nginx:alpine
ports:
- "8080:80"
EOF
# 启动服务
docker compose up -d
# 检查运行状态
docker compose ps
# 访问测试
curl localhost:8080 # 应返回 Nginx 欢迎页
# 清理测试
docker compose down
常见问题解决
-
权限错误:
bashsudo chown $USER:$USER $HOME/.docker -R
-
命令未找到:
bash# 检查插件路径 echo $DOCKER_CONFIG ls -l $DOCKER_CONFIG/cli-plugins # 系统级安装方案 sudo mkdir -p /usr/local/lib/docker/cli-plugins sudo cp $HOME/.docker/cli-plugins/docker-compose /usr/local/lib/docker/cli-plugins/
-
版本过旧:
bash# 手动更新 rm ~/.docker/cli-plugins/docker-compose # 重新执行手动安装步骤
重要提示 :所有 v2 命令使用
docker compose
(带空格),不再是 v1 的docker-compose
(带连字符)
7️⃣ 参考 7 四个系统目录对比
/usr/local/lib/docker/cli-plugins
/usr/local/libexec/docker/cli-plugins
/usr/lib/docker/cli-plugins
/usr/libexec/docker/cli-plugins
对比
对比 1
Docker Compose V2 系统级安装目录对比
以下是对四个系统级安装目录的详细对比分析:
目录路径 | 推荐度 | 适用场景 | 权限要求 | 特点 |
---|---|---|---|---|
/usr/local/lib/docker/cli-plugins |
★★★★★ | 首选推荐位置 | 需 sudo |
标准手动安装目录,与系统包隔离,最符合 Linux FHS 规范 |
/usr/local/libexec/docker/cli-plugins |
★★★★☆ | 替代方案 | 需 sudo |
libexec 通常存放内部二进制文件,较少用作插件目录 |
/usr/lib/docker/cli-plugins |
★★☆☆☆ | 包管理器安装 | 需 sudo |
系统级库目录,易与包管理器冲突,不推荐手动安装 |
/usr/libexec/docker/cli-plugins |
★★☆☆☆ | 特殊系统配置 | 需 sudo |
系统内部执行目录,非常规插件位置,可能被系统更新覆盖 |
核心结论
-
首选目录
✅
/usr/local/lib/docker/cli-plugins
-
理由 :符合 Linux FHS 标准的第三方软件位置
-
示例命令 :
bashsudo mkdir -p /usr/local/lib/docker/cli-plugins sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) -o /usr/local/lib/docker/cli-plugins/docker-compose sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
-
-
备选目录
⚠️
/usr/local/libexec/docker/cli-plugins
- 仅当 主目录不可用时作为替代方案
-
避免使用的目录
❌
/usr/lib/docker/cli-plugins
和/usr/libexec/docker/cli-plugins
- 风险 :
- 可能被系统包管理器(apt/yum)覆盖
- 与 Docker 官方安装包冲突
- 违反 Linux 目录规范
- 风险 :
最佳实践建议
bash
# 1. 创建推荐目录
sudo mkdir -p /usr/local/lib/docker/cli-plugins
# 2. 下载 Compose V2
sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) \
-o /usr/local/lib/docker/cli-plugins/docker-compose
# 3. 添加执行权限
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
# 4. 验证安装
docker compose version
关键说明:
- 使用
/usr/local/
目录可确保:
- 手动安装与系统包隔离
- 避免未来 Docker 升级冲突
- 符合 Linux 系统管理规范
- 通过
which docker-compose
检查是否存在旧版冲突文件
对比 2
以下是四个 Docker Compose 系统级安装目录的详细对比分析:
目录路径 | 用途定位 | 适用场景 | 优先级 | 系统标准 |
---|---|---|---|---|
/usr/local/lib/docker/cli-plugins |
用户级本地安装目录 | 手动安装首选位置,避免与系统包冲突 | 最高 | 符合 FHS 标准 |
/usr/local/libexec/docker/cli-plugins |
本地执行目录(libexec 变体) | 备用安装位置 | 中 | 符合 FHS 标准 |
/usr/lib/docker/cli-plugins |
系统级库目录 | 包管理器(apt/yum)自动安装位置 | 低 | 符合 FHS 标准 |
/usr/libexec/docker/cli-plugins |
系统执行目录(libexec 变体) | 较少使用 | 最低 | 部分发行版特有 |
关键差异详解
-
路径层级差异
/usr/local/
前缀:用户手动安装位置(避免覆盖系统文件)/usr/
前缀:系统级安装位置(包管理器默认使用)
-
目录类型差异
lib
:标准库目录(存放共享库和插件)libexec
:内部执行目录(存放不直接执行的辅助程序)
-
实际使用建议
bash# 最佳实践:优先使用标准库目录 sudo mkdir -p /usr/local/lib/docker/cli-plugins sudo curl -SL https://github.com/docker/compose/releases/download/v2.24.7/docker-compose-linux-$(uname -m) \ -o /usr/local/lib/docker/cli-plugins/docker-compose sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
-
优先级验证 Docker 按以下顺序查找插件:
bash1. ~/.docker/cli-plugins # 用户级目录(最高优先级) 2. /usr/local/lib/docker/cli-plugins 3. /usr/local/libexec/docker/cli-plugins 4. /usr/lib/docker/cli-plugins 5. /usr/libexec/docker/cli-plugins # 系统级目录(最低优先级)
特殊场景说明
- 容器环境 :在 Docker-in-Docker 场景中,建议使用
/usr/local/lib/docker/cli-plugins
- 多架构系统 :ARM 设备(如树莓派)优先使用
/usr/local/
目录 - 安全加固系统 :SELinux 环境下,
/usr/libexec/
可能有特殊权限策略
历史背景 :
libexec
目录源于 Unix 传统,用于存放不应被用户直接执行的内部二进制文件,现代 Linux 系统中逐渐被lib
目录替代。Docker 保留这些路径主要为兼容旧系统。
对比 3
以下是针对四个 Docker CLI 插件目录的详细对比分析:
目录路径 | 系统定位 | 适用场景 | 权限要求 | 优先级 | 兼容性 |
---|---|---|---|---|---|
/usr/local/lib/docker/cli-plugins |
用户级安装目录 | 手动安装时首选位置 | 需 sudo 权限 |
★★★★☆ | 所有 Linux 发行版 |
/usr/local/libexec/docker/cli-plugins |
系统级执行目录 | 特殊系统环境(较少使用) | 需 sudo 权限 |
★★☆☆☆ | BSD 系系统更常见 |
/usr/lib/docker/cli-plugins |
系统级库目录 | 包管理器安装(apt/yum/dnf) | 包管理器自动处理 | ★★★☆☆ | 主流 Linux 发行版 |
/usr/libexec/docker/cli-plugins |
系统级执行目录 | 特殊包管理场景(如 RPM 特定安装) | 包管理器自动处理 | ★★☆☆☆ | RHEL/CentOS/Fedora |
关键差异解析
-
路径含义差异:
lib
:通用库目录(推荐)libexec
:内部执行目录(专用场景)
-
安装方式区别:
bash# 手动安装首选(用户级) sudo install docker-compose /usr/local/lib/docker/cli-plugins/ # 包管理器安装(系统级) sudo apt install docker-compose-plugin # 自动安装到 /usr/lib/...
-
Docker 识别优先级: 当存在多个安装时,Docker 按此顺序识别: 1. ~/.docker/cli-plugins/ (用户目录) 2. /usr/local/lib/docker/cli-plugins/ 3. /usr/lib/docker/cli-plugins/ 4. /usr/local/libexec/... 和 /usr/libexec/... (最后检查)
-
最佳实践:
- 个人开发环境 :使用
~/.docker/cli-plugins
(无需 sudo) - 多用户系统 :
/usr/local/lib/docker/cli-plugins
- 生产服务器 :通过包管理器安装到
/usr/lib/...
- 个人开发环境 :使用
验证路径配置
bash
# 检查 Docker 搜索路径
docker info --format '{{range .ClientInfo.Plugins}}{{.Path}}{{"\n"}}{{end}}'
# 典型输出示例:
/home/user/.docker/cli-plugins
/usr/local/lib/docker/cli-plugins
/usr/lib/docker/cli-plugins
故障排查技巧 若命令无法识别:
bash
# 检查所有候选路径
ls -d /usr/local/lib*/docker/cli-plugins \
/usr/lib*/docker/cli-plugins \
~/.docker/cli-plugins 2>/dev/null
# 临时添加测试路径
export DOCKER_CLI_PLUGINS_PATH="/custom/path:$DOCKER_CLI_PLUGINS_PATH"
重要提示 :Docker v20.10+ 默认支持该插件架构,旧版本需升级 Docker Engine 才能使用
docker compose
命令。
8️⃣ 参考 8 五个目录的优先级对比
~/.docker/cli-plugins
($HOME/.docker/cli-plugins
)/usr/local/lib/docker/cli-plugins
/usr/local/libexec/docker/cli-plugins
/usr/lib/docker/cli-plugins
/usr/libexec/docker/cli-plugins
优先级对比
优先级对比 1
Docker Compose V2 安装目录优先级对比
以下是按 优先级从高到低 的目录排序(基于 Docker CLI 的插件加载规则):
优先级 | 目录路径 | 适用场景 | 特点说明 |
---|---|---|---|
1 | ~/.docker/cli-plugins 或 $HOME/.docker/cli-plugins |
用户级安装(推荐) | ✅ 优先级最高 ❌ 仅对当前用户有效 🔧 无需 root 权限 |
2 | /usr/local/lib/docker/cli-plugins |
系统级安装(首选) | ✅ 符合 FHS 标准 🛡️ 与系统包隔离 💻 对所有用户有效 |
3 | /usr/local/libexec/docker/cli-plugins |
备选系统目录 | ⚠️ 非常规位置 📦 可能被误清理 🔍 较少使用 |
4 | /usr/lib/docker/cli-plugins |
包管理器专用目录 | ❗️ 易与 apt/yum 冲突 🔄 可能被系统更新覆盖 ⛔️ 不推荐手动安装 |
5 | /usr/libexec/docker/cli-plugins |
系统内部目录 | 🚫 最低优先级 🧩 通常存放守护进程 ⚠️ 强烈不建议使用 |
关键结论
-
最高优先级:用户目录 (
~/.docker/cli-plugins
) ($HOME/.docker/cli-plugins
)-
优势:无需 sudo,独立配置
-
命令示例 :
bashmkdir -p ~/.docker/cli-plugins curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) -o ~/.docker/cli-plugins/docker-compose chmod +x ~/.docker/cli-plugins/docker-compose
-
-
最佳系统目录:
/usr/local/lib/docker/cli-plugins
-
推荐场景:多用户系统/生产环境
-
安装示范 :
bashsudo mkdir -p /usr/local/lib/docker/cli-plugins sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) -o /usr/local/lib/docker/cli-plugins/docker-compose sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
-
-
避坑指南:
-
❌ 避免使用
/usr/lib/
和/usr/libexec/
开头的目录- 易导致与包管理器冲突(如 apt 安装的 Docker)
- 可能被系统更新意外覆盖
-
🔍 检查现有安装:
bash# 查看 Compose 实际加载路径 docker compose version --short
-
优先级验证原理 :
Docker CLI 按以下顺序扫描插件目录:
$HOME/.docker/cli-plugins
- 全局自定义目录(如
/usr/local/lib/docker/cli-plugins
)- Docker 内置目录(如
/usr/lib/docker/cli-plugins
)
找到第一个有效插件后立即停止搜索
优先级对比 2
以下是 Docker Compose CLI 插件搜索路径的优先级详细对比分析,按优先级从高到低排序:
优先级排序(1 → 5 优先级递减)
优先级 | 路径 | 搜索顺序 | 适用场景 | 权限要求 |
---|---|---|---|---|
1 | ~/.docker/cli-plugins 或 $HOME/.docker/cli-plugins |
最先 | 用户级安装 • 无需 root 权限 • 仅影响当前用户 | 用户级权限 |
2 | /usr/local/lib/docker/cli-plugins |
次之 | 系统级手动安装首选 • 全局可用 • 不干扰系统包管理 | 需 sudo 权限 |
3 | /usr/local/libexec/docker/cli-plugins |
第三 | 备选系统路径 • 较少使用 • 兼容旧系统 | 需 sudo 权限 |
4 | /usr/lib/docker/cli-plugins |
第四 | 包管理器默认路径 • apt/yum 安装位置 • 可能被系统更新覆盖 | 包管理器管理 |
5 | /usr/libexec/docker/cli-plugins |
最后 | 特殊系统路径 • 极少使用 • 某些发行版保留目录 | 需 sudo 权限 |
关键特性对比
特性 | ~/.docker |
/usr/local/lib |
/usr/local/libexec |
/usr/lib |
/usr/libexec |
---|---|---|---|---|---|
多用户隔离 | ✅ 独立 | ❌ 全局 | ❌ 全局 | ❌ 全局 | ❌ 全局 |
系统更新安全性 | ✅ 不受影响 | ✅ 不受影响 | ✅ 不受影响 | ⚠️ 可能被覆盖 | ✅ 不受影响 |
容器环境兼容性 | ✅ 最佳 | ✅ 良好 | ⚠️ 一般 | ⚠️ 可能有冲突 | ❌ 差 |
权限要求 | 用户级 | sudo | sudo | 包管理器 | sudo |
版本控制灵活性 | ✅ 可自由切换 | ✅ 可自由切换 | ✅ 可自由切换 | ❌ 依赖包管理 | ✅ 可自由切换 |
实际使用场景推荐
-
开发环境首选 →
~/.docker/cli-plugins
bash# 无需sudo,安全隔离 mkdir -p ~/.docker/cli-plugins curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) \ -o ~/.docker/cli-plugins/docker-compose chmod +x ~/.docker/cli-plugins/docker-compose
-
生产环境推荐 →
/usr/local/lib/docker/cli-plugins
bash# 全局可用,避免用户隔离问题 sudo mkdir -p /usr/local/lib/docker/cli-plugins sudo curl -SL [下载链接] -o /usr/local/lib/docker/cli-plugins/docker-compose sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
-
应避免的路径 →
/usr/lib*/docker/cli-plugins
- 易与包管理器冲突
- 可能被系统更新意外覆盖
优先级验证方法
bash
# 创建测试插件
echo -e '#!/bin/sh\necho "Plugin from: $0"' > docker-testplugin
# 在所有路径放置同名文件
cp docker-testplugin ~/.docker/cli-plugins/
sudo cp docker-testplugin /usr/local/lib/docker/cli-plugins/
sudo cp docker-testplugin /usr/local/libexec/docker/cli-plugins/
sudo cp docker-testplugin /usr/lib/docker/cli-plugins/
sudo cp docker-testplugin /usr/libexec/docker/cli-plugins/
# 添加执行权限
chmod +x ~/.docker/cli-plugins/*
sudo chmod +x /usr/*/docker/cli-plugins/*
# 运行测试(显示最高优先级路径)
docker testplugin
# 输出: Plugin from: /home/youruser/.docker/cli-plugins/docker-testplugin
故障排查提示 :当命令不生效时,使用
which -a docker-compose
检查是否存在旧版 v1 冲突,或使用strace -e file docker compose version 2>&1 | grep cli-plugins
查看实际加载路径。
优先级对比 3
Docker Compose V2 安装目录优先级详解(从高到低)
优先级顺序表
排名 | 目录路径 | 类型 | 权限要求 | 特点 | 推荐指数 |
---|---|---|---|---|---|
1 | ~/.docker/cli-plugins 或 $HOME/.docker/cli-plugins |
用户级 | 无需sudo | ✅ 最高优先级 🔐 仅影响当前用户 💻 开发环境首选 | ⭐⭐⭐⭐⭐ |
2 | /usr/local/lib/docker/cli-plugins |
系统级 | 需sudo | 🏆 最佳系统目录 📦 符合FHS标准 🛡️ 与系统包隔离 | ⭐⭐⭐⭐☆ |
3 | /usr/local/libexec/docker/cli-plugins |
系统级 | 需sudo | ⚠️ 次选系统目录 📁 较少使用 🔧 特殊场景备用 | ⭐⭐⭐☆☆ |
4 | /usr/lib/docker/cli-plugins |
系统级 | 需sudo | ❗ 易冲突 🔄 可能被apt/yum覆盖 ⛔ 不推荐手动安装 | ⭐⭐☆☆☆ |
5 | /usr/libexec/docker/cli-plugins |
系统级 | 需sudo | 🚫 最低优先级 🧩 系统守护进程目录 ⚠️ 强烈不建议使用 | ⭐☆☆☆☆ |
关键机制解析
-
搜索顺序原理
Docker CLI 按以下顺序扫描插件目录:
graph LR A[用户目录] --> B[ /usr/local/lib] --> C[ /usr/local/libexec] --> D[ /usr/lib] --> E[ /usr/libexec]- 找到即停:发现有效插件后立即终止搜索
- 权限优先:用户级目录 > 系统级目录
-
目录特性对比
特性 用户目录 /usr/local/lib /usr/lib 多用户共享 ❌ 仅当前用户 ✅ 所有用户 ✅ 所有用户 系统更新影响 🔒 不受影响 🔒 不受影响 ⚠️ 可能被覆盖 包管理器冲突风险 🟢 无风险 🟢 无风险 🔴 高风险 FHS标准符合性 ✅ 符合 ✅ 符合 ⚠️ 系统保留目录
最佳实践指南 场景1:个人开发环境
bash
# 首选用户级安装(无需sudo)
mkdir -p ~/.docker/cli-plugins
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose
场景2:生产服务器/多用户系统
bash
# 使用最佳系统目录
sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) -o /usr/local/lib/docker/cli-plugins/docker-compose
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
应避免的目录
bash
# 危险示例(可能导致系统冲突)
sudo curl ... -o /usr/lib/docker/cli-plugins/docker-compose # ❌
sudo curl ... -o /usr/libexec/docker/cli-plugins/docker-compose # ❌
优先级验证方法
bash
# 1. 检查实际加载的插件路径
docker compose version --short
# 2. 查看Docker的插件搜索路径
docker info --format '{{range .ClientInfo.Plugins}}{{.Path}}{{"\n"}}{{end}}'
# 3. 检测目录存在性(按优先级顺序)
ls -d ~/.docker/cli-plugins \
/usr/local/lib/docker/cli-plugins \
/usr/local/libexec/docker/cli-plugins \
/usr/lib/docker/cli-plugins \
/usr/libexec/docker/cli-plugins 2>/dev/null
关键结论 :
用户级目录 (
~/.docker/cli-plugins
) 和系统级目录 (/usr/local/lib/docker/cli-plugins
) 是唯二推荐的选择,其他目录存在兼容性风险或违反Linux目录规范。
优先级对比 4
以下是 Docker CLI 插件目录优先级的专业对比说明,按照从高到低的顺序排列(1为最高优先级):
优先级排序(数字越小优先级越高)
优先级 | 目录路径 | 类型 | 适用场景 | 检查顺序 |
---|---|---|---|---|
1 | ~/.docker/cli-plugins 或 $HOME/.docker/cli-plugins |
用户级 | 开发者个人环境,无需sudo权限 | 最先检查 |
2 | /usr/local/lib/docker/cli-plugins |
系统级 | 管理员手动安装首选位置 | 次之 |
3 | /usr/local/libexec/docker/cli-plugins |
系统级 | BSD系统或特殊环境 | 第三 |
4 | /usr/lib/docker/cli-plugins |
系统级 | 包管理器安装位置(apt/yum/dnf) | 第四 |
5 | /usr/libexec/docker/cli-plugins |
系统级 | RPM系发行版专用位置 | 最后检查 |
关键差异分析
-
用户级 vs 系统级:
-
~/.docker/cli-plugins
优先级最高,因为:bash# 无需sudo即可安装 curl -o ~/.docker/cli-plugins/docker-compose ... chmod +x ~/.docker/cli-plugins/docker-compose
-
其他目录需要root权限
-
-
手动安装 vs 包管理安装:
-
/usr/local/...
(手动安装)优先级高于/usr/...
(包管理安装) -
示例:手动安装覆盖包管理版本
bashsudo install docker-compose /usr/local/lib/docker/cli-plugins/ # 优先级高于apt安装版本
-
-
lib vs libexec:
- 同级别下
lib
优先于libexec
/usr/local/lib > /usr/local/libexec
/usr/lib > /usr/libexec
- 同级别下
优先级验证方法
bash
# 1. 创建测试插件
cat <<'EOF' > docker-test
#!/bin/sh
echo "Active plugin from: $0"
EOF
chmod +x docker-test
# 2. 在所有目录安装同名插件
install_paths=(
"$HOME/.docker/cli-plugins"
"/usr/local/lib/docker/cli-plugins"
"/usr/local/libexec/docker/cli-plugins"
"/usr/lib/docker/cli-plugins"
"/usr/libexec/docker/cli-plugins"
)
for path in "${install_paths[@]}"; do
sudo mkdir -p "$path"
sudo cp docker-test "$path/docker-test" # 需要sudo权限
done
# 3. 执行测试(显示最高优先级路径)
docker test
# 输出:Active plugin from: /home/yourname/.docker/cli-plugins/docker-test
# 4. 删除用户级插件后重试
rm ~/.docker/cli-plugins/docker-test
docker test
# 输出:Active plugin from: /usr/local/lib/docker/cli-plugins/docker-test
特殊规则
-
环境变量覆盖:
bash# 设置自定义路径(最高优先级) export DOCKER_CLI_PLUGINS_PATH="/custom/plugins:/other/plugins" docker test # 只检查指定路径
-
同目录多版本处理:
- 同一目录内按文件名排序取第一个
- 避免在多个目录安装同名插件
-
网络插件优先级:
- 本地插件 > 网络插件(Docker Hub下载的插件)
最佳实践建议
-
开发环境:
bash# 用户级安装(推荐) mkdir -p ~/.docker/cli-plugins curl -L https://.../docker-compose -o ~/.docker/cli-plugins/docker-compose chmod +x ~/.docker/cli-plugins/docker-compose
-
生产环境:
bash# 系统级安装(选择优先级2的目录) sudo curl -L https://.../docker-compose -o /usr/local/lib/docker/cli-plugins/docker-compose sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
-
故障排查:
bash# 检查插件搜索路径 docker info --format '{{range .ClientInfo.Plugins}}{{.Path}}{{"\n"}}{{end}}' # 检查插件是否存在 which -a docker-compose # 显示所有路径
优先级对比 5
Docker CLI 插件目录优先级详解
优先级从高到低排序:
优先级 | 目录路径 | 用户影响范围 | 典型使用场景 | 权限要求 |
---|---|---|---|---|
1 | ~/.docker/cli-plugins 或 $HOME/.docker/cli-plugins |
单用户 | 用户专属插件/测试版本 | 用户权限 |
2 | /usr/local/lib/docker/cli-plugins |
所有用户 | 管理员手动安装的共享插件 | sudo |
3 | /usr/local/libexec/docker/cli-plugins |
所有用户 | Docker内部组件/特殊用途插件 | sudo |
4 | /usr/lib/docker/cli-plugins |
所有用户 | 系统包管理器(apt/yum)安装的插件 | sudo |
5 | /usr/libexec/docker/cli-plugins |
所有用户 | Docker守护进程专用插件 | sudo |
关键特性对比
- 加载顺序机制
bash
# 查看实际加载顺序
docker info --format '{{range .ClientInfo.PluginsPaths}}{{.}}{{"\n"}}{{end}}'
# 典型输出(按优先级降序):
/home/yourname/.docker/cli-plugins
/usr/local/lib/docker/cli-plugins
/usr/local/libexec/docker/cli-plugins
/usr/lib/docker/cli-plugins
/usr/libexec/docker/cli-plugins
- 同名插件冲突解决
- 当多个目录存在同名插件时:
- 用户级优先 :
~/.docker/cli-plugins
中的插件始终优先执行 - 同级别顺序:系统级目录按文件系统枚举顺序(通常字典序)
- 用户级优先 :
- 目录用途差异
目录类型 | 典型内容 | 修改频率 |
---|---|---|
~/.docker/ |
用户自定义插件、开发测试版本 | 高 |
/usr/local/ |
手动安装的生产插件 | 中 |
/usr/lib/ |
系统包管理器维护的稳定版本 | 低 |
*/libexec/ |
Docker内部组件(如buildx) | 极低 |
最佳实践指南
个人开发环境
bash
# 用户级安装 (优先级最高)
mkdir -p ~/.docker/cli-plugins
curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 \
-o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose
多用户生产服务器
bash
# 系统级安装 (推荐)
sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo curl -L https://github.com/docker/compose/releases/latest/download/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
特殊场景说明
-
覆盖系统插件:
bash# 在用户目录放置同名插件可覆盖系统级插件 cp custom-compose ~/.docker/cli-plugins/docker-compose
-
诊断插件冲突:
bash# 检查实际加载的插件路径 which -a docker-compose | xargs ls -l # 查看Docker识别的插件路径 docker compose version --short
-
libexec
目录警告:- 避免手动修改
*/libexec/
目录 - Docker会自动管理这些目录的内容
- 手动放置文件可能导致版本冲突
- 避免手动修改
优先级黄金法则 :
用户级(
~/.docker
) > 手动安装(/usr/local
) > 系统包管理(/usr/lib
) > 内部目录(libexec
)生产环境推荐使用
/usr/local/lib/docker/cli-plugins
平衡控制力和可维护性。