Distrobox: 在你的Linux终端里“塞"入任意发行版,实现无缝多环境体验

指南 | Guides 2025年9月17日

First | 序

本文将深入剖析 Distrobox，一个让你在终端里无缝集成多个发行版的利器

📦

本篇所使用到的操作系统&软件版本如下所示

📃

目录/标题如下所示

1. About Distrobox | 关于 Distrobox

Distrobox 是一个高级封装工具，为实现最大程度的可移植性而采用 POSIX shell 编写，其核心功能是管理 OCI 容器，以便将任何 Linux 发行版的用户空间（userland）集成到宿主系统中。它本身并非容器管理器，而是一个构建于现有容器运行时（如 Podman 或 Docker）之上的用户体验层。

1.1. Use Cases | 应用场景

增强不可变操作系统(在只读根文件系统中创建可变环境)
隔离的开发环境
软件兼容性
在无 sudo 权限的设置中提供特权环境
混合搭配发行版(基础系统+自定义最新环境和软件包)
......

1.2. What is Tightly Integrated | 什么是紧密集成?

紧密集成 是 Distrobox 的标志性特征
它通过与容器共享宿主机的关键资源，实现了近乎原生的使用体验
宿主机可选择共享如下内容

用户家目录
硬件和设备(外挂的外部存储,USB)
图形和音频会话
系统服务
......

1.3. Under the Hood | 如何工作的 ?

按照如下命令创建 tumbleweed-bpftrace 容器为例

distrobox create --root --name tumbleweed-bpftrace --image registry.opensuse.org/opensuse/distrobox-bpftrace:latest

接着使用 Podman inspect tumbleweed-bpftrace 命令详细看一下

[
  {
    "Id": "b0d971f4b880...",
    "Name": "tumbleweed-bpftrace",
    "ImageName": "registry.opensuse.org/opensuse/distrobox-bpftrace:latest",
    "Created": "2025-09-15T08:25:05.337364913+08:00",
    "Path": "/usr/bin/entrypoint",
    "Args": [
        "--verbose",
        "--name",
        "root",
        "--user",
        "0",
        "--group",
        "0",
        "--home",
        "/root",
        "..."
    ],
    "State": {
        "Status": "running",
        "Pid": 127971,
        "StartedAt": "2025-09-15T22:11:15.489178866+08:00"
    },
    // Distrobox 的核心是与主机系统的深度集成，通过大量挂载实现
    "Mounts": [
        {
            "Type": "bind",
            "Source": "/usr/bin/distrobox-init",
            "Destination": "/usr/bin/entrypoint",
            "RW": false
        },
        {
            "Type": "bind",
            "Source": "/home",
            "Destination": "/run/host/home",
            "RW": true
        },
        {
            "Type": "bind",
            "Source": "/root",
            "Destination": "/root",
            "RW": true
        },
        {
            "Type": "bind",
            "Source": "/usr",
            "Destination": "/run/host/usr",
            "RW": false
        }
        // ... 此处省略了其他众多用于集成主机文件系统的挂载点 ...
    ],
    "Config": {
        "Env": [
            "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
            "container= podman",
            "TERMINFO_DIRS=/usr/share/terminfo:/run/host/usr/share/terminfo",
            "CONTAINER_ID=tumbleweed-bpftrace",
            "SHELL=zsh",
            "HOME=/root",
            "HOSTNAME=microos-k3s"
        ],
        "Labels": {
            "manager": "distrobox",
            "distrobox.unshare_groups": "0",
            "org.opencontainers.image.title": "Distrobox openSUSE bpftrace container"
        },
        // 这个创建命令是理解 Distrobox 如何配置容器的最关键信息
        "CreateCommand": [
            "podman",
            "create",
            "--hostname",
            "microos-k3s",
            "--name",
            "tumbleweed-bpftrace",
            "--privileged",
            "--security-opt",
            "label=disable",
            "--ipc",
            "host",
            "--network",
            "host",
            "--pid",
            "host",
            "--label",
            "manager=distrobox",
            // ... 此处省略了数十个用于挂载主机目录的 --volume 参数 ...
            "--entrypoint",
            "/usr/bin/entrypoint",
            "registry.opensuse.org/opensuse/distrobox-bpftrace:latest",
            "--verbose",
            "--name",
            "root",
            "--home",
            "/root",
            "..."
        ]
    },
    // 主机配置显示了 Distrobox 如何利用 Podman 的高级功能与系统集成
    "HostConfig": {
        "Privileged": true,
        "NetworkMode": "host",
        "PidMode": "host",
        "IpcMode": "host",
        "SecurityOpt": [
            "label=disable",
            "apparmor=unconfined",
            "unmask=all"
        ],
        "PidsLimit": -1
    }
  }
]

⚠️

Key Takeaways | 关键要点

Distrobox 大概通过以下几步实现

劫持容器入口点 Entrypoint
使用特权模式启动容器
共享宿主机 Namespace
禁用一些安全选项

2. Installation | 安装

Distrobox 软件包一般都存在于发行版的存储库中可以直接安装

Debian

apt install distrobox

openSUSE

zypper install distrobox

Fedora / RHEL

dnf install podman

openSUSE MicroOS

transactional-update pkg install distrobox

⚠️

注意

若你有如下需求可以使用 curl 或者 wget 安装

存储库版本较低或者你想尝试新版本

curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sudo sh

指定安装目录从而规避一些sudo问题

使用 --prefix 参数指定

curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --prefix ~/.local

⚓

Dependencies | 依赖项

Distrobox 依赖容器管理器才能正常工作

容器管理器依赖项及其最低版本要求如下

Podman：最低版本要求是 2.1.0
Docker 客户端：最低版本要求是 19.03.15
Lilipod：最低版本要求是 v0.0.1

官方推荐且默认使用 Podman
因为 Docker 配置 Rootless 太麻烦

同时 OCI 镜像也应包含如下内容已确保容器的正常运行和与宿主的良好集成

基本的 Linux 实用程序 (mount)
基本的用户管理实用程序 (useradd & passwd)
sudo 工具

3. Usage | 使用

Distrobox 的使用非常简单

基本就是如下一些核心命令

我们一一解析

distrobox version: 1.8.1.2

Choose one of the available commands:
        assemble
        create
        enter
        list | ls
        rm
        stop
        upgrade
        ephemeral
        generate-entry
        version
        help

📔

Distrobox 核心命令快速参考

命令	功能	上下文 (运行位置)
`distrobox-create`	创建一个新的 Distrobox 容器。	宿主机
`distrobox-enter`	进入一个已存在的容器或在其中执行命令。	宿主机
`distrobox-list`	列出所有已创建的容器及其状态。	宿主机
`distrobox-stop`	停止一个正在运行的容器。	宿主机
`distrobox-rm`	删除一个容器。	宿主机
`distrobox-upgrade`	更新一个或多个容器内的软件包。	宿主机
`distrobox-ephemeral`	创建一个临时的、用后即毁的容器。	宿主机
`distrobox-assemble`	根据清单文件批量创建或销毁容器。	宿主机
`distrobox-generate-entry`	为容器本身创建桌面启动项。	宿主机
`distrobox-export`	将应用、二进制文件或服务从容器导出到宿主机。	容器内部
`distrobox-host-exec`	从容器内部在宿主机上执行命令。	容器内部

3.1. distrobox-create

distrobox-create 是创建新容器的核心命令,常用的可选参数如下所示

参数 (Parameter)	说明 (Description)	默认值 (Default)
`--image` / `-i`	用于创建容器的镜像	`registry.opensuse.org/opensuse/distrobox:latest`
`--name` / `-n`	为 distrobox 命名	`my-distrobox`
`--hostname`	为 distrobox 指定主机名	`microos-k3s`
`--pull` / `-p`	即使本地存在镜像也强制拉取（隐含 `--yes`）	无
`--yes` / `-Y`	非交互模式，无需确认直接拉取镜像	无
`--root` / `-r`	使用 root 权限启动 podman/docker/lilipod。这是需要 root 权限时的首选方式，优于 `sudo distrobox`。	无
`--clone` / `-c`	克隆一个已存在的 distrobox 容器作为新容器的基础。用于重命名或复制环境。	无
`--home` / `-H`	为容器选择一个自定义的 HOME 目录。有助于避免主机 HOME 目录中产生临时文件。	无
`--volume`	向容器添加额外的卷	无
`--additional-flags` / `-a`	传递给容器管理器的额外参数	无
`--additional-packages` / `-ap`	在容器初始化设置期间额外安装的软件包	无
`--init-hooks`	在容器初始化结束时执行的额外命令	无
`--pre-init-hooks`	在容器初始化开始时执行的额外命令	无
`--init` / `-I`	在容器内使用初始化系统（如 systemd），这将使主机的进程在容器内不可见。	无

EXAMPLES | 示例

使用 registry.opensuse.org/opensuse/distrobox-bpftrace:latest 镜像使用root权限创建一个名为 tumbleweed-bpftrace 的容器
```
distrobox create --root --name tumbleweed-bpftrace --image registry.opensuse.org/opensuse/distrobox-bpftrace:latest
```
使用 registry.opensuse.org/opensuse/distrobox-bpftrace:latest 镜像使用root权限创建一个名为 tumbleweed-bpftrace 的容器并指定家目录为 /home/tumbleweed-bpftrace
```
distrobox create --root --name tumbleweed-bpftrace --home /home/tumbleweed-bpftrace --image registry.opensuse.org/opensuse/distrobox-bpftrace:latest
```
使用 --init 选项可以在容器内使用 systemd 以增强独立性,当你想在容器中再嵌套docker/podman/lxc时候需要和unshare-all配合使用,这样以来容器进程将不会挂在宿主机上而是会独立出来,同时容器也将无法访问宿主机的进程

以在 Distrobox 中使用 Podman为例
```
distrobox create --root \
  --image registry.opensuse.org/opensuse/distrobox:latest \
  --additional-packages "podman" \
  --unshare-all
```

3.2. distrobox-list

distrobox-list 用于列出已创建的容器

帮助信息如下所示:

distrobox version: 1.8.1.2

Usage:

        distrobox-list

Options:

        --help/-h:              show this message
        --no-color:             disable color formatting
        --root/-r:              launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
                                way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
                                specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
        --verbose/-v:           show more verbosity
        --version/-V:           show version

EXAMPLES | 示例

distrobox list $name

3.3. distrobox-enter

distrobox-enter 用于和安装的容器进行交互,可选参数如下所示

参数 (Parameter)	说明 (Description)	默认值 (Default)
`--name` / `-n`	指定要进入的 distrobox 的名称	`my-distrobox`
`--` / `-e`	在指定的容器内执行某个命令，并将结果输出到当前的终端，但并不会进入该容器的交互式Shell环境。	默认用户的 shell
`--clean-path`	将容器内的 `PATH` 环境变量重置为 FHS 标准	无
`--no-tty` / `-T`	不分配 TTY (终端)	无
`--no-workdir` / `-nw`	始终从容器的 HOME 目录启动，而不是当前工作目录	无
`--additional-flags` / `-a`	传递给容器管理器的额外参数	无
`--help` / `-h`	显示帮助信息	无
`--root` / `-r`	使用 root 权限启动 podman/docker/lilipod。这是需要 root 权限时的首选方式，优于 `sudo distrobox`。	无
`--dry-run` / `-d`	仅打印生成的容器管理器命令，而不执行	无
`--verbose` / `-v`	显示更详细的输出	无
`--version` / `-V`	显示版本信息	无

EXAMPLES | 示例

进入名为 arch-test 容器的交互式 shell 环境
```
distrobox enter arch-test
```
进入名为 arch-test 容器的交互式 shell 环境执行 fastfetch 命令后结束
```
distrobox enter arch-test -e fastfetch
```

3.4. distrobox-stop

distrobox stop 用于暂停容器(默认情况下退出容器环境后容器将会在后台继续运行)

帮助信息如下所示:

distrobox version: 1.8.1.2

Usage:

        distrobox-stop --name container-name
        distrobox-stop container-name

Options:

        --all/-a:               stop all distroboxes
        --yes/-Y:               non-interactive, stop without asking
        --help/-h:              show this message
        --root/-r:              launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
                                way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
                                specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
        --verbose/-v:           show more verbosity
        --version/-V:           show version

示例如下

暂停名为 arch-test 的容器
```
distrobox stop arch-test
```
暂停所有容器
```
distrobox stop --all/-a
```

3.5. distrobox-rm

distrobox rm 用于删除已创建容器

帮助信息如下所示:

distrobox rm -h
distrobox version: 1.8.1.2

Usage:

        distrobox-rm [-f/--force] container-name [container-name1 container-name2 ...]

Options:

        --all/-a:               delete all distroboxes
        --force/-f:             force deletion
        --rm-home:              remove the mounted home if it differs from the host user's one
        --root/-r:              launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
                                way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
                                specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
        --help/-h:              show this message
        --verbose/-v:           show more verbosity
        --version/-V:           show version

EXAMPLES | 示例

删除名为 arch-test 的容器
```
distrobox rm arch-test
```
强制删除名为 arch-test 的容器
```
distrobox rm -f arch-test
```

4. Advanced Topics | 高级用法

4.1. distrobox-assemble

distrobox-assemble 允许用户在一个清单文件(通常命名为 distrobox.ini)中以代码即基础设施 (Infrastructure as Code)的方式(这里是声明式)定义一组容器。这种方法使得环境的创建变得可复现、自动化，并且可以进行版本控制。

👩‍🏫

知识点

清单文件采用INI格式
distrobox-assemble create ：创建清单文件中定义的所有容器
distrobox-assemble rm：销毁清单文件中定义的所有容器
支持通过 URL 使用清单文件: distrobox-assemble create --file https://.../distrobox.ini
使用 --dry-run 标志可以打印出将要执行的命令，而不会实际运行它们，便于调试和验证

📜

distrobox.ini 清单文件选项参考

键名	类型	描述
`additional_flags`	字符串列表	传递给容器管理器的额外标志。
`additional_packages`	字符串列表	在容器初始化期间额外安装的软件包。
`home`	字符串	容器应使用的 HOME 目录路径。
`image`	字符串	容器应使用的 OCI 镜像。
`clone`	字符串	要克隆的现有 Distrobox 容器的名称（必须已停止）。
`init_hooks`	字符串列表	在软件包设置后，在容器内部运行的命令。
`pre_init_hooks`	字符串列表	在软件包设置前，在容器内部运行的命令。
`init`	布尔值	指定这是否是一个启用 init 的容器（默认为 `false`）。
`nvidia`	布尔值	指定是否启用 NVIDIA 驱动集成（默认为 `false`）。
`root`	布尔值	指定容器是否为 rootful（默认为 `false`）。
`pull`	布尔值	指定是否每次都拉取镜像（默认为 `false`）。
`start_now`	布尔值	指定是否立即启动容器（默认为 `false`）。
`entry`	布尔值	是否为容器生成一个应用列表中的条目（默认为 `false`）。
`volume`	字符串列表	额外挂载到容器内部的卷。
`exported_apps`	字符串列表	要导出的应用名称或 `.desktop` 文件路径。
`exported_bins`	字符串列表	要导出的二进制文件路径。
`exported_bins_path`	字符串	导出二进制文件的可选路径（默认为 `$HOME/.local/bin`）。
`unshare_ipc`	布尔值	是否解绑 IPC 命名空间（默认为 `false`）。
`unshare_netns`	布尔值	是否解绑网络命名空间（默认为 `false`）。
`unshare_process`	布尔值	是否解绑进程（PID）命名空间（默认为 `false`）。
`unshare_devsys`	布尔值	是否解绑 `/dev`（默认为 `false`）。
`unshare_all`	布尔值	是否解绑以上所有命名空间（默认为 `false`）。

EXAMPLES | 示例

以下复制官方文件示例,建议结合上方文件内容对号入座加深理解

5. FAQ

Q: Distrobox & Podman 是什么关系?

A: Distrobox 是一个上层封装工具，它使用 Podman（或 Docker）作为底层技术，来创建和管理紧密集成的容器化命令行环境

Q: Distrobox & Toolbox是什么关系?

A: 起初 Distrobox 灵感来源于 Toolbox 但其目前属于两个不同的项目,可以理解为Distrobox是Toolbox的超集

Q: Distrobox 对不可变、原子化操作系统而言意味着什么?

A: 传统的Linux发行版长期以来面临着系统可靠性和“依赖地狱”等问题。原子化操作系统的出现又催生了一个新挑战,而 Distrobox 补齐了此块短板,其在Fedora Silverblue/Kinoite、SteamOS、openSUSE Aeon/Kalpa/MicroOS 和 Vanilla OS 等只读系统之上,提供了一个可变的、持久化的软件层,解决了在只读文件系统上安装和管理传统软件包的难题。

Q: 使用Distrobox需要做哪些取舍?

A: Distrobox 优先考虑的是便利性和集成,而非严格的安全隔离.因此,在实践中,用户应采取最佳实践,如隔离 HOME 目录,并将其与 Flatpak 等更侧重于沙箱的技术结合使用,以构建一个既灵活又相对安全的计算环境.

向你推荐

指南 | Guides

openSUSE MicroOS 安装 Cockpit 及配置虚拟化实践

4 个月前 • 阅读预计需要3分钟

指南 | Guides

Kured(KUbernetes REboot Daemon) with openSUSE MicroOS

5 个月前 • 阅读预计需要15分钟

实践 | Practices

openSUSE MicroOS Rebootmgr & systemd-inhibit

10 个月前 • 阅读预计需要10分钟

openSUSE MicroOS 安装 Cockpit 及配置虚拟化实践

Intel® XL710-QDA1 with Lenovo ThinkCentre Tiny Compatibility Guide(兼容性指南)

Kured(KUbernetes REboot Daemon) with openSUSE MicroOS

bpftune - BPF driven auto-tuning | install & usage

Distrobox: 在你的Linux终端里“塞"入任意发行版,实现无缝多环境体验

First | 序

1. About Distrobox | 关于 Distrobox

1.1. Use Cases | 应用场景

1.2. What is Tightly Integrated | 什么是紧密集成?

1.3. Under the Hood | 如何工作的 ?

2. Installation | 安装

Debian

openSUSE

Fedora / RHEL

openSUSE MicroOS

3. Usage | 使用

3.1. distrobox-create

EXAMPLES | 示例

3.2. distrobox-list

EXAMPLES | 示例

3.3. distrobox-enter

EXAMPLES | 示例

3.4. distrobox-stop

示例如下

3.5. distrobox-rm

EXAMPLES | 示例

4. Advanced Topics | 高级用法

4.1. distrobox-assemble

EXAMPLES | 示例

5. FAQ

Q: Distrobox & Podman 是什么关系?

Q: Distrobox & Toolbox是什么关系?

Q: Distrobox 对不可变、原子化操作系统而言意味着什么?

Q: 使用Distrobox需要做哪些取舍?

标签

xzllll

向你推荐

openSUSE MicroOS 安装 Cockpit 及配置虚拟化实践

Kured(KUbernetes REboot Daemon) with openSUSE MicroOS

openSUSE MicroOS Rebootmgr & systemd-inhibit

openSUSE MicroOS 安装 Cockpit 及配置虚拟化实践

Intel® XL710-QDA1 with Lenovo ThinkCentre Tiny Compatibility Guide(兼容性指南)

Kured(KUbernetes REboot Daemon) with openSUSE MicroOS

bpftune - BPF driven auto-tuning | install & usage

First | 序

1. About Distrobox | 关于 Distrobox

1.1. Use Cases | 应用场景

1.2. What is Tightly Integrated | 什么是紧密集成?

1.3. Under the Hood | 如何工作的 ?

2. Installation | 安装

Debian

openSUSE

Fedora / RHEL

openSUSE MicroOS

3. Usage | 使用

3.1. distrobox-create

EXAMPLES | 示例

3.2. distrobox-list

EXAMPLES | 示例

3.3. distrobox-enter

EXAMPLES | 示例

3.4. distrobox-stop

示例如下

3.5. distrobox-rm

EXAMPLES | 示例

4. Advanced Topics | 高级用法

4.1. distrobox-assemble

EXAMPLES | 示例

5. FAQ

Q: Distrobox & Podman 是什么关系?

Q: Distrobox & Toolbox是什么关系?

Q: Distrobox 对不可变、原子化操作系统而言意味着什么?

Q: 使用Distrobox需要做哪些取舍?

标签

订阅我们的新内容

xzllll

向你推荐

openSUSE MicroOS 安装 Cockpit 及配置虚拟化实践

Kured(KUbernetes REboot Daemon) with openSUSE MicroOS

openSUSE MicroOS Rebootmgr & systemd-inhibit