Debian is one of the most reliable Linux distributions available, but its commitment to stability comes with a well-known tradeoff: packages can lag behind the bleeding edge by months or even years. If you have ever needed a newer version of a tool, a package only available on Ubuntu, or wanted to test software across multiple distributions without leaving your current system, you already know the frustration. Distrobox solves this problem directly by letting you run any Linux distribution inside your terminal as a tightly integrated container, sharing your home directory, USB devices, audio, and even graphical applications over X11 or Wayland.

This guide walks you through exactly how to install Distrobox on Debian 13 (codenamed Trixie), which was officially released on August 9, 2025. You will cover four installation methods, set up Podman as the recommended container runtime, create and manage containers, export desktop applications to your host launcher, and fix the most common errors that come up during setup. Every command is tested and explained so you understand not just what to run but why it works.

Whether you are a developer who wants to test code against multiple Linux environments, a sysadmin who needs legacy tools on a modern host, or a power user who wants the latest version of an application without risking your stable Debian base, this guide has you covered.

What Is Distrobox and Why Use It on Debian 13?

Distrobox is an open-source project maintained by Luca Di Maio (89luca89 on GitHub) that wraps around Podman, Docker, or Lilipod to create containers from any OCI-compatible Linux image. The key difference between Distrobox and a standard container is integration depth. A Distrobox container shares your HOME directory, Wayland and X11 sockets, networking stack, removable devices, the systemd journal, SSH agent, D-Bus, and the udev database. The result is a container that feels like a native part of your system.

Debian 13 Trixie ships with the Linux 6.12 LTS kernel, APT 3.0 with the new deb822 sources format, GNOME 48, KDE Plasma 6.3, and full riscv64 architecture support. This modern foundation makes Trixie an excellent Distrobox host. Importantly, Distrobox is now included in Debian 13’s official package repositories, meaning you can install it with a single apt command without touching any third-party scripts.

Here is when Distrobox genuinely earns its place on a Debian 13 system:

• You need a newer version of a package than what Trixie ships
• You want to run Ubuntu, Fedora, or Arch tools without dual booting
• You are developing and need to test across multiple distros from one machine
• You want to export a GUI application from a container directly into your GNOME or KDE launcher
• You need legacy toolchains or older library versions for a specific project without polluting your host

Distrobox is not a virtual machine. It does not emulate hardware or boot a second kernel. It uses the host kernel, which keeps resource usage minimal and startup times under a second for already-created containers.

Prerequisites

Before you start, make sure the following are in place:

• Operating system: Debian 13 Trixie (stable, released August 9, 2025)
• User privileges: A non-root user account with sudo access
• Internet connection: Required to pull packages and container images
• Terminal access: A local terminal or SSH session
• Architecture: amd64, arm64, or riscv64 (all supported by Trixie)
• Container runtime: Podman (recommended) or Docker must be installed before Distrobox can create containers. Minimum supported versions: Podman 2.1.0 or Docker 19.03.15
• Kernel namespaces: Rootless Podman requires user namespace support, which is enabled by default in Debian 13’s kernel

If you are on a fresh Debian 13 install, run a full system update before proceeding to avoid dependency conflicts.

Step 1: Update Your Debian 13 System

Always start a new software installation by updating your package index and upgrading existing packages. Outdated dependencies are the most common source of silent installation failures.

sudo apt update && sudo apt upgrade -y

What this does: apt update refreshes the local package lists from all configured repositories. apt upgrade -y applies all available upgrades without prompting for each package. The -y flag automatically confirms all prompts.

Expected output:

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Calculating upgrade... Done
The following packages will be upgraded:
  ...

If your system shows 0 upgraded, 0 newly installed, you are already current and can move directly to the next step.

Step 2: Install and Configure Podman on Debian 13

Distrobox needs a container manager to function. Podman is the recommended choice over Docker for three reasons: it runs completely daemonless, it operates in rootless mode by default, and it does not require any background service to be running. Rootless Podman means containers run entirely under your user account, which reduces the system attack surface compared to Docker’s root daemon model.

Install Podman

sudo apt install podman -y

Verify the installation and confirm the version is 2.1.0 or higher:

podman --version

Expected output:

podman version 4.x.x

Configure Rootless User Namespaces

Debian 13 typically creates the /etc/subuid and /etc/subgid entries automatically when you create a user with adduser. Verify your username appears in both files:

cat /etc/subuid
cat /etc/subgid

Expected output (replace youruser with your actual username):

youruser:100000:65536

If your username is missing from either file, add the entries manually:

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER

After running this command, log out and back in for the changes to take effect. This step is critical. Rootless Podman cannot create user namespaces without valid subordinate UID and GID ranges.

Optional: Use Docker Instead of Podman

If you prefer Docker, install it as follows:

sudo apt install docker.io -y
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Log out and back in after adding your user to the docker group. Note that Docker requires the daemon to be running at all times, while Podman does not.

Step 3: Install Distrobox on Debian 13

Debian 13 Trixie includes Distrobox in its official repositories, so Method 1 below is the cleanest path for most users. Additional methods are provided for users who want the latest upstream version or have specific environment requirements.

Method 1: Install via APT (Recommended)

This is the simplest and most maintainable method. Packages installed through APT receive automatic security updates when you run apt upgrade.

sudo apt install distrobox -y

Verify the installation:

distrobox --version

Expected output:

distrobox: 1.x.x

Run distrobox --help to see all available subcommands and confirm the binary is in your PATH.

Method 2: Install via Curl Script (Latest Upstream)

Use this method when you want the most recent upstream release directly from the Distrobox GitHub project. Always inspect the script before running it in production.

System-wide installation (requires sudo):

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

Per-user installation (no sudo required):

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

If you installed per-user, add ~/.local/bin to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Using wget instead of curl:

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

Method 3: Install via Snap

Use this method if you are already using Snap on Debian 13. First, install and bootstrap snapd:

sudo apt install snapd -y
sudo snap install snapd

Then install Distrobox from the edge channel:

sudo snap install distrobox --edge

Be aware that Snap’s sandbox layer can occasionally conflict with Distrobox’s deep host integration. The APT method avoids this entirely.

Method 4: Install from the Git Repository

This method suits developers who want to track the latest commits or contribute to the Distrobox project.

git clone https://github.com/89luca89/distrobox.git
cd distrobox
sudo ./install

For a per-user install to a custom prefix:

./install --prefix ~/.local

The binaries land in ${prefix}/bin and man pages in ${prefix}/share/man.

Step 4: Create Your First Distrobox Container

With Distrobox and Podman installed, you can now pull any OCI-compatible Linux image and spin up a container. Distrobox supports images from Docker Hub, quay.io, and any other OCI-compatible registry.

Basic Container Creation

The core syntax for creating a container is:

distrobox create --name  --image 

Example: Create an Ubuntu 24.04 container:

distrobox create --name ubuntu-box --image ubuntu:24.04

Example: Create a Fedora 40 container:

distrobox create --name fedora-dev --image fedora:40

Example: Create an Arch Linux container:

distrobox create --name arch-test --image archlinux:latest

On the first run, Distrobox pulls the image from the remote registry. This takes a few minutes depending on your connection speed. Subsequent create calls for the same image are nearly instant since the image is cached locally.

Create a Container with a Separate Home Directory

If you want to isolate a container’s home data from your main $HOME:

distrobox create --name isolated-box --image debian:trixie --home ~/distrobox/isolated

This is useful when you want a completely clean environment for a specific project without any of your dotfiles leaking in.

Create a Container with Systemd Support

For workflows that require systemd services inside the container:

distrobox create --name systemd-box --init --image ubuntu:24.04 --additional-packages "systemd libpam-systemd pipewire-audio-client-libraries"

The --init flag tells Distrobox to set up the container with a full init system.

List All Containers

distrobox list

Expected output:

ID           | NAME        | STATUS   | IMAGE
-------------|-------------|----------|------------------
abc123def456 | ubuntu-box  | created  | ubuntu:24.04
789xyz000111 | fedora-dev  | created  | fedora:40

Step 5: Enter and Use a Distrobox Container

Creating a container is only the first step. You need to enter it to install packages and do real work.

Enter a Container

distrobox enter ubuntu-box

The first time you enter a container, Distrobox runs a one-time initialization routine. It installs a minimal set of integration packages inside the container to enable HOME sharing, display forwarding, and audio. This is completely normal and only happens once per container.

After initialization completes, your terminal prompt changes to reflect the container environment. You are now inside the Ubuntu container.

Verify the Environment

Run these commands inside the container to confirm you are in a different distribution while still on the same kernel:

cat /etc/os-release

Output inside the Ubuntu container:

NAME="Ubuntu"
VERSION="24.04 LTS (Noble Numbat)"

uname -r

This returns the Debian 13 host kernel version because Distrobox containers share the host kernel. They do not boot their own.

Use the Container’s Package Manager

Inside an Ubuntu container, use apt:

sudo apt update && sudo apt install htop -y

Inside a Fedora container, use dnf:

sudo dnf install htop -y

Inside an Arch container, use pacman:

sudo pacman -Syu htop

Packages installed inside a container stay inside that container. They do not touch your host Debian system’s package database.

Exit the Container

exit

The container persists after you exit. Your data, installed packages, and configuration are all saved. Next time you run distrobox enter ubuntu-box, you are back in the same environment instantly.

Step 6: Export Applications to Your Debian 13 Desktop

One of Distrobox’s most powerful capabilities is its ability to export installed applications from a container directly into your Debian 13 desktop launcher or shell PATH. This lets you run container apps as if they are native host applications.

Export a GUI Application

First, install the application inside the container:

distrobox enter ubuntu-box
sudo apt install firefox -y

Then export it to the host without leaving the container:

distrobox-export --app firefox

Distrobox creates a .desktop file in ~/.local/share/applications/ on the host. The app now appears in your GNOME or KDE application launcher and launches automatically from the container.

Export a CLI Binary to the Host PATH

distrobox-export --bin /usr/bin/htop --export-path ~/.local/bin

Now you can run htop from any terminal on the host, even outside the container. Distrobox transparently starts the container in the background when you run the exported binary.

Remove an Exported Application

distrobox-export --app firefox --delete

This removes the .desktop file from the host without affecting the application inside the container.

Step 7: Manage and Maintain Distrobox Containers

Stop a Running Container

distrobox stop ubuntu-box

Remove a Container

distrobox rm ubuntu-box

This removes the container but not the image. You can recreate it at any time with the same distrobox create command.

Force Remove a Container and Its Data

distrobox rm --force ubuntu-box

Use this carefully. It deletes the container and any data stored in the container’s internal directories.

Upgrade Packages Inside a Container Without Entering It

distrobox upgrade ubuntu-box

This is useful for scripting automated maintenance across multiple containers.

Use Distrobox Assemble for Reproducible Setups

Distrobox-assemble lets you define containers in a declarative INI-style configuration file, which is ideal for reproducible environments across machines.

Create a file named myboxes.ini:

[ubuntu-box]
image=ubuntu:24.04
additional_packages=git vim tmux curl

[fedora-dev]
image=fedora:40
additional_packages=gcc make cmake python3

Run all containers defined in the file:

distrobox assemble create --file ~/myboxes.ini

Troubleshooting Common Distrobox Issues on Debian 13

Error: “distrobox: command not found” After Per-User Install

Cause: The ~/.local/bin directory is not in your $PATH.

Fix:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify it works:

which distrobox

Error: “WARN rootless… requires /etc/subuid”

Cause: Your username is missing from /etc/subuid or /etc/subgid.

Fix:

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER

Log out and back in, then retry.

Error: Container Initialization Hangs at First Entry

Cause: Slow mirrors during the one-time initialization package install inside the container.

Fix: Check your internet connectivity. If the connection is fine, force a fresh image pull and recreate:

distrobox rm ubuntu-box
podman pull ubuntu:24.04
distrobox create --name ubuntu-box --image ubuntu:24.04

Error: GUI Applications Do Not Display

Cause: DISPLAY or WAYLAND_DISPLAY environment variables are not set or not forwarded into the container.

Fix on a local desktop session: Debian 13 sets these variables automatically in GNOME and KDE. If they are missing, run:

echo $DISPLAY
echo $WAYLAND_DISPLAY

If both return empty, your display server may not be running. Restart your desktop session.

Fix for SSH sessions:

ssh -X youruser@yourserver

The -X flag enables X11 forwarding over SSH.

Error: Image Pull Fails with “toomanyrequests”

Cause: Docker Hub rate limits anonymous pull requests to 100 per 6 hours.

Fix: Authenticate with your Docker Hub account:

podman login docker.io

Enter your Docker Hub username and password. Authenticated pulls have a much higher rate limit.

Congratulations! You have successfully installed Distrobox. Thanks for using this tutorial for installing the latest version of Distrobox on Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official Distrobox website.