Distrobox 安装与后端配置

本文的命令接口按 Distrobox 1.8.2.5 官方脚本核对；镜像标签与发行版包名是示例，使用前确认镜像仍受支持、仓库可用及本机实际版本。示例未做运行验证。

本文介绍如何在 Linux 系统上安装 Distrobox 及其依赖项，完成首次初始化，并针对不同使用场景选择合适的容器后端。

1. 前置依赖#

Distrobox 本身是一组 shell 脚本，不依赖任何特定运行时。但它需要至少一个可用的容器管理器来创建和运行容器。

1.1 容器后端要求

Distrobox 支持的三种后端及其最低版本要求：

Podman 的 rootless 模式适合用户级环境，Distrobox 会配置 guest 用户及 UID 映射来降低文件属主冲突。Docker 也支持 rootless；不能把后端类型直接等同于所有 guest 进程的身份。无论后端如何，共享 HOME 都允许容器程序修改宿主用户文件。

1.2 检查容器后端是否工作

安装完成后，用以下命令验证后端是否可以正常拉取镜像并运行容器：

# Podman
podman run --rm hello-world

# Docker
docker run --rm hello-world

期望输出中应包含类似 Hello from Docker! 或 !... Hello Podman World ...! 的欢迎信息。如果报错 permission denied 或 cannot connect to daemon，说明后端未正确安装或服务未启动。

1.3 验证 Rootless 配置（Podman 用户必做）

Podman 的 rootless 模式依赖 /etc/subuid 和 /etc/subgid 为当前用户分配从属 UID/GID 范围。检查当前用户是否已配置：

# 查看是否有从属 ID 映射
grep "^$(whoami):" /etc/subuid /etc/subgid

期望输出类似：

/etc/subuid:user:100000:65536
/etc/subgid:user:100000:65536

如果没有输出，说明 rootless 未配置。手动分配示例（需要 sudo；先检查所有用户已有范围，示例区间必须未占用且不重叠。NixOS 使用声明式配置，不手改生成文件）：

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 "$(whoami)"

变更映射后先停止相关容器，再按 Podman 文档使用 podman system migrate 更新 rootless pause 进程；这会影响当前用户的容器，不是简单重启某个必需守护进程。

关于 Rootless 的原理 详细原理和故障排查见 Podman Rootless 容器。简单来说：宿主机分配不重叠的 subordinate UID/GID 范围用于映射多个 guest 身份；UID 0 的具体映射取决于 user namespace 配置，Distrobox keep-id 与普通 Podman 默认映射不同。

2. 安装 Distrobox#

Distrobox 提供三种安装方式，按推荐度排列如下。

2.1 包管理器安装（推荐）

以下是常见包管理器安装方式，仓库分支、包版本与最低发行版支持需按当前发行版确认：

NixOS 用户 NixOS 上 Distrobox 与 Nix 环境交互有特殊注意事项——详见本系列 子文档 06：NixOS 与声明式容器。

包管理器安装的优点：

• 发行版可处理打包依赖；仍需检查可用的 Podman、Docker 或 Lilipod 后端
• 随系统更新自动升级
• 文件安装到发行版管理的路径，NixOS 通常在 Nix store 与 profile 中

2.2 Curl 安装脚本

适合不想用包管理器、或需要安装到非标准路径的场景（如无 sudo 权限时安装到用户目录）：

# 下载固定版本的安装脚本，先阅读再执行；不自动安装容器后端
curl -fL https://raw.githubusercontent.com/89luca89/distrobox/1.8.2.5/install -o distrobox-install
less distrobox-install
# 用户目录安装示例
sh distrobox-install --prefix "$HOME/.local"
# 系统前缀需要相应权限，按需选择，勿与包管理器安装混用
# sudo sh distrobox-install --prefix /usr/local
# sudo sh distrobox-install --prefix /opt/distrobox

该 1.8.2.5 安装器内置 version=1.8.2.5；未使用 --next 时下载对应 tag。也可使用下一节的 tag checkout，从本地源码目录安装。

关键参数说明：

安装脚本的行为：

• 将 distrobox 主程序和辅助脚本（distrobox-create、distrobox-enter、distrobox-list 等）复制到 <prefix>/bin/
• 安装的默认配置及文档布局以版本与发行版打包为准，不能假定一定存在一个可列举全部选项的 distrobox.conf
• 将 man 手册页复制到 <prefix>/share/man/
• 不会自动安装容器后端——Podman 或 Docker 需要单独安装

安装脚本的局限 安装脚本不处理依赖关系，不会安装 podman 或 docker。如果你还没有容器后端，请先参考 Podman 安装指南 或发行版仓库安装 podman。

2.3 从源码手动安装（Git Clone）

适合想贡献代码或需要自定义修改的高级用户：

# 克隆仓库
git clone https://github.com/89luca89/distrobox.git
cd distrobox
git checkout 1.8.2.5

# 直接运行（无需安装）
./distrobox --help

# 从固定版本源码目录运行安装器
./install --prefix "$HOME/.local"

手动安装后需要自行处理 PATH——确保 <prefix>/bin/ 在你的 $PATH 中。如果用 ~/.local/bin，大多数现代发行版的 shell 配置已自动包含该路径。

3. 后端选择与配置#

Distrobox 通过优先级链决定使用哪个容器管理器，并提供三种方式显式指定。

3.1 Podman vs Docker vs Lilipod 对比

3.2 指定容器管理器的方式

Distrobox 脚本先载入安装/系统/用户配置，再应用受支持的环境变量；存在的 CLI 选项随后覆盖相应设置。后端选择用 DBX_CONTAINER_MANAGER 或配置 container_manager，1.8.2.5 的 create/enter 没有 --container-manager 选项。

graph TD
    A["DBX_CONTAINER_MANAGER"] --> B["会话或单次调用覆盖"]
    C["用户配置"] --> D["覆盖系统配置"]
    E["系统与安装配置"] --> F["默认设置"]
    G["无显式后端"] --> H["自动检测 Podman / Docker / Lilipod"]

方式一：单次环境变量指定

DBX_CONTAINER_MANAGER=podman distrobox create --name mybox --image ubuntu:24.04
DBX_CONTAINER_MANAGER=podman distrobox enter mybox

Podman 与 Docker 的容器存储独立；后续操作要选择创建时的后端，不能假定容器会跨后端自动找到。

方式二：环境变量（会话级）

# 当前终端会话中强制使用 Podman
export DBX_CONTAINER_MANAGER=podman

# 或者永久生效（写入 shell 配置文件）
echo 'export DBX_CONTAINER_MANAGER=podman' >> ~/.bashrc
# fish 使用自身语法
# set -gx DBX_CONTAINER_MANAGER podman

方式三：配置文件（持久化，推荐）

创建用户级配置文件 ~/.config/distrobox/distrobox.conf：

mkdir -p ~/.config/distrobox

cat > ~/.config/distrobox/distrobox.conf << 'EOF'
# Distrobox 用户级配置文件
# 选项见当前版本官方脚本和文档；配置文件按 shell 代码读取

# 指定默认容器管理器（podman / docker / lilipod）
container_manager="podman"

# 拉取镜像时总是更新（0 / 1）
container_always_pull=0

# 容器首次初始化末尾运行的 hook，非每次启动服务
# container_init_hook=""

# 创建容器时预拉取的额外包
# container_additional_packages=""

# 默认使用非交互模式（0 / 1）
non_interactive=0

# enter 时不使用宿主当前工作目录
# skip_workdir=1
EOF

配置文件使用 shell 语法，并由脚本 source 读取，因此也能执行命令；只加载可信配置。安装默认文件的位置取决于前缀或 Nix store，系统文件、$XDG_CONFIG_HOME/distrobox/distrobox.conf 与 ~/.distroboxrc 的覆盖顺序应查当前脚本。

多后端共存时可固定 container_manager="podman"，单次切换用 DBX_CONTAINER_MANAGER=docker distrobox ...。切换后端并不会迁移容器。

3.3 自动检测逻辑

如果不做任何配置，Distrobox 会按以下顺序自动检测可用的后端：

# Distrobox 内部检测逻辑（简化版）
if command -v podman >/dev/null 2>&1; then
    container_manager="podman"
elif command -v docker >/dev/null 2>&1; then
    container_manager="docker"
elif command -v lilipod >/dev/null 2>&1; then
    container_manager="lilipod"
else
    echo "Error: no container manager found."
    exit 1
fi

这基本是"有 Podman 就用 Podman，否则 Fallback 到 Docker"的策略，与官方推荐一致。

4. 首次运行验证#

完成安装和配置后，按以下步骤验证 Distrobox 是否正常工作。

4.1 检查版本

# 查看版本号，确认安装成功
distrobox version
# 或
distrobox --version

期望输出示例：

distrobox: 1.8.1.2

如果报 command not found，检查安装路径是否在 $PATH 中：

which distrobox
# 或
ls ~/.local/bin/distrobox /usr/local/bin/distrobox /usr/bin/distrobox

4.2 创建测试容器

# 用 Ubuntu 24.04 创建一个名为 "test" 的容器
distrobox create --name test --image ubuntu:24.04

# 期望输出
# Creating 'test' using image ubuntu:24.04  [ OK ]
# Distrobox 'test' successfully created.

关键参数说明：

首次创建会从 Docker Hub 拉取镜像，需等待网络下载完成。镜像大小因发行版而异（压缩/展开大小、架构和 tag 均会改变）。

4.3 进入容器并验证

# 进入测试容器
distrobox enter test

进入后你会注意到 shell 提示符发生了变化（默认会加容器名前缀）。在容器内执行以下验证：

# 1. 确认发行版信息
cat /etc/os-release | head -5

# 2. 确认 HOME 目录与宿主机共享——输出的路径应该和宿主机一致
echo $HOME

# 3. 确认宿主机文件可见
ls $HOME/Documents

# 4. 确认可以安装包（测试容器内包管理器）
sudo apt update && sudo apt install -y procps
ps -ef | head

# 5. 测试 GUI 应用（需要 X11 或 Wayland 支持）
# 安装一个带 GUI 的小工具测试
sudo apt install -y x11-apps
xeyes &        # 应该弹出一对跟随鼠标的眼睛

# 或者用 glxgears 测试 OpenGL
sudo apt install -y mesa-utils
glxgears       # 应该弹出一个旋转齿轮的窗口

GUI 应用不弹出 如果 xeyes 或 glxgears 报错 cannot open display，说明 X11/Wayland 转发未生效。检查：

1. 宿主机上确认 echo $DISPLAY 或 echo $WAYLAND_DISPLAY 有值
2. 检查 /etc/subuid 和 /etc/subgid 是否正确配置（见第 1.3 节）
3. 尝试退出并重新进入：exit 后 distrobox enter test

# 6. 退出容器
exit

4.4 查看容器列表

# 列出所有容器及其状态
distrobox list

# 期望输出示例：
# ID   | NAME | STATUS        | IMAGE
# a1b2c3d4e5f6 | test | Up 5 minutes | ubuntu:24.04

4.5 清理测试容器

验证完成后删除测试容器：

# 停止并删除容器
distrobox stop test
distrobox rm test

# 或者一步到位（跳过停止直接强制删除）
distrobox rm test --force
# -f 是 --force 的简写

验证清单

• distrobox version 输出版本号
• distrobox create 成功拉取镜像并创建容器
• distrobox enter 成功进入容器 shell
• 容器内 $HOME 与宿主机一致
• 容器内能安装和管理包
• GUI 应用能正常显示（可选，取决于显示转发配置）
• distrobox list 能看到容器
• distrobox rm --force 成功删除容器

下一步

安装配置完成后，进入 子文档 03：镜像与容器管理，学习如何创建和管理日常使用的容器。