Distrobox installation and backend configuration

The command interfaces in this article were checked against the official Distrobox 1.8.2.5 scripts. Image tags and distribution package names are examples; before using them, confirm that the images are still supported, the repositories are available, and your installed version matches your needs. The examples have not been tested by running them.

This article explains how to install Distrobox and its dependencies on Linux, complete the initial setup, and choose a suitable container backend for different use cases.

1. Prerequisites#

Distrobox itself is a collection of shell scripts with no dependency on a particular runtime. However, it requires at least one working container manager to create and run containers.

1.1 Container Backend Requirements

Distrobox supports three backends, with the following minimum version requirements:

Podman's rootless mode suits user-level environments. Distrobox configures the guest user and UID mappings to reduce file ownership conflicts. Docker also supports rootless mode; the backend type alone does not determine the identity of every guest process. Regardless of the backend, sharing HOME allows container programs to modify the host user's files.

1.2 Checking That the Container Backend Works

After installation, use the following commands to verify that the backend can pull images and run containers:

# Podman
podman run --rm hello-world

# Docker
docker run --rm hello-world

The expected output includes a greeting such as Hello from Docker! or !... Hello Podman World ...!. Errors such as permission denied or cannot connect to daemon indicate that the backend is not installed correctly or its service is not running.

1.3 Verifying Rootless Configuration (Required for Podman Users)

Podman's rootless mode relies on /etc/subuid and /etc/subgid to allocate subordinate UID/GID ranges to the current user. Check whether the current user is configured:

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

Expected output resembles:

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

If there is no output, rootless mode is not configured. Here is an example of manual allocation (requires sudo; first inspect every user's existing ranges. The example range must be unused and nonoverlapping. On NixOS, use declarative configuration instead of manually editing generated files):

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

After changing mappings, stop the affected containers first, then follow the Podman documentation to use podman system migrate to update the rootless pause process. This affects the current user's containers; it is not simply restarting some required daemon.

How Rootless Works: For a detailed explanation and troubleshooting, see Podman Rootless Containers. In brief, the host allocates nonoverlapping subordinate UID/GID ranges to map multiple guest identities. The specific mapping of UID 0 depends on the user namespace configuration; Distrobox's keep-id differs from ordinary Podman's default mapping.

2. Installing Distrobox#

Distrobox offers three installation methods, listed below in order of preference.

2.1 Installation with a Package Manager (Recommended)

The following are common package-manager installation methods. Confirm repository branches, package versions, and minimum supported distribution releases for your current distribution:

NixOS Users: Interactions between Distrobox and the Nix environment require special care on NixOS. See Part 06: NixOS and Declarative Containers in this series.

Advantages of installing with a package manager:

• The distribution can handle packaging dependencies; you still need to check that a working Podman, Docker, or Lilipod backend is available
• Automatically upgraded with system updates
• Files are installed to distribution-managed paths, usually in the Nix store and profiles on NixOS

2.2 Curl Installation Script

Useful when you do not want to use a package manager or need to install to a nonstandard location, such as a user directory without sudo access:

# 下载固定版本的安装脚本，先阅读再执行；不自动安装容器后端
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

This 1.8.2.5 installer has version=1.8.2.5 built in and downloads the corresponding tag unless --next is used. Alternatively, check out a tag as described in the next section and install from the local source directory.

Key parameters:

The installation script:

• Copies the main distrobox program and helper scripts (distrobox-create, distrobox-enter, distrobox-list, etc.) into <prefix>/bin/
• Installs default configuration and documentation according to the version and distribution packaging; do not assume there is always a distrobox.conf listing every option
• Copies man pages into <prefix>/share/man/
• Does not automatically install a container backend; install Podman or Docker separately

Limitations of the Installation Script: The script does not resolve dependencies or install podman or docker. If you do not already have a container backend, consult the Podman installation guide or use your distribution's repository to install podman first.

2.3 Manual Installation from Source (Git Clone)

Suitable for advanced users who want to contribute code or make custom changes:

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

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

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

After manual installation, manage PATH yourself: ensure <prefix>/bin/ is in your $PATH. If you use ~/.local/bin, most modern distributions already include this path in their shell configuration.

3. Backend Selection and Configuration#

Distrobox selects a container manager through a priority chain and provides three ways to specify one explicitly.

3.1 Podman vs Docker vs Lilipod

3.2 Ways to Specify the Container Manager

Distrobox scripts first load installation/system/user configuration, then apply supported environment variables. Available CLI options subsequently override the corresponding settings. Select the backend with DBX_CONTAINER_MANAGER or the container_manager configuration setting; create/enter in 1.8.2.5 has no --container-manager option.

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

Method One: An Environment Variable for One Invocation

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

Podman and Docker maintain separate container stores. Subsequent operations must use the backend that created the container; do not assume containers are found automatically across backends.

Method Two: A Session-Level Environment Variable

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

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

Method Three: A Configuration File (Persistent, Recommended)

Create the user-level configuration file ~/.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

Configuration files use shell syntax and are sourced by the scripts, so they can execute commands; load only trusted configuration. The location of installation defaults depends on the prefix or Nix store. Check the current scripts for the override order of system files, $XDG_CONFIG_HOME/distrobox/distrobox.conf, and ~/.distroboxrc.

When multiple backends coexist, set container_manager="podman" as the default and use DBX_CONTAINER_MANAGER=docker distrobox ... for a one-off switch. Switching backends does not migrate containers.

3.3 Automatic Detection Logic

Without any configuration, Distrobox automatically detects available backends in the following order:

# 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

This is essentially “use Podman if available, otherwise fall back to Docker,” consistent with the official recommendation.

4. Verifying the First Run#

After installation and configuration, follow these steps to verify that Distrobox works correctly.

4.1 Check the Version

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

Example expected output:

distrobox: 1.8.1.2

If you see command not found, check whether the installation directory is in $PATH:

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

4.2 Create a Test Container

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

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

Key parameters:

The first creation pulls the image from Docker Hub, so wait for the network download to finish. Image size varies by distribution; compressed/extracted sizes, architecture, and tag all affect it.

4.3 Enter the Container and Verify It

# 进入测试容器
distrobox enter test

After entering, you will notice that the shell prompt changes (by default, it gains a container-name prefix). Run the following checks inside the container:

# 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 Application Does Not Appear: If xeyes or glxgears reports cannot open display, X11/Wayland forwarding is not working. Check the following:

1. On the host, confirm that echo $DISPLAY or echo $WAYLAND_DISPLAY has a value
2. Check that /etc/subuid and /etc/subgid are configured correctly (see Section 1.3)
3. Try exiting and re-entering: run exit, then distrobox enter test

# 6. 退出容器
exit

4.4 List Containers

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

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

4.5 Remove the Test Container

After verification, remove the test container:

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

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

Verification Checklist

• distrobox version prints a version number
• distrobox create successfully pulls an image and creates a container
• distrobox enter successfully opens the container shell
• $HOME inside the container matches the host
• Packages can be installed and managed inside the container
• GUI applications display correctly (optional; depends on display forwarding configuration)
• distrobox list shows the container
• distrobox rm --force successfully removes the container

Next Steps

With installation and configuration complete, continue to Part 03: Image and Container Management to learn how to create and manage containers for everyday use.