Distrobox: Run Any Linux Distribution in a Container on Your Desktop

If you have ever wanted to run a command-line tool that is only available on Ubuntu while working on Fedora, or needed to test an application across multiple distributions without spinning up virtual machines, Distrobox solves exactly that problem. It is one of the most useful tools to appear in the Linux ecosystem in recent years, and once you understand how it works, you will wonder how you managed without it.

Table of Contents

• What Is Distrobox
• How Distrobox Works Under the Hood
• Installing Distrobox
• Creating Your First Container
• Working Inside Distrobox Containers
• Exporting Applications to the Host
• Real-World Use Cases
• Distrobox vs Docker vs Toolbox vs Podman
• Advanced Usage and Configuration
• Troubleshooting Common Issues

What Is Distrobox

Distrobox is a tool that uses Podman or Docker to run any Linux distribution inside your terminal, with seamless integration with the host system. Unlike running a full virtual machine or a traditional container, a Distrobox container shares your home directory, your network, your display server (Wayland and X11 both work), your audio system, and your USB devices. The result feels less like a container and more like a parallel Linux environment that happens to use different packages.

The project was created by Luca di Maio and has become a first-class tool on distributions like Fedora Silverblue, Bazzite, and uBlue, where the host system is immutable and packages cannot be installed directly. On these systems, Distrobox is the recommended way to install developer tools, experimental software, or anything that requires a traditional mutable package environment.

How Distrobox Works Under the Hood

Distrobox pulls a container image from a registry (Docker Hub, Quay.io, or any OCI-compatible registry) and starts it with a carefully crafted set of flags that bind-mount host resources into the container. The key insight is that the container shares several namespaces with the host rather than fully isolating from it.

When you enter a Distrobox container, the tool automatically installs a small init system inside the container, sets up your user account with the same UID and GID as the host user, mounts /home, /run/user, /tmp, and display-related sockets. This means your files are immediately accessible, GUI applications open on your desktop, and audio plays through your host speakers without any configuration.

Distrobox works with both Podman (the default, recommended option) and Docker. On systems where Podman is available rootless, the entire stack runs without any elevated privileges.

Installing Distrobox

Prerequisites

You need either Podman or Docker installed before installing Distrobox. Podman is preferred because it runs rootless by default.

# Fedora / RHEL / Rocky Linux
sudo dnf install podman distrobox

# Ubuntu / Debian
sudo apt install podman distrobox

# Arch Linux
sudo pacman -S distrobox

# Any distribution using the official installer
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --prefix ~/.local

Verify Installation

distrobox version
podman --version

If you are on an immutable distribution like Fedora Silverblue, Bazzite, or Aurora, Distrobox is typically included by default. You can also install it as a Flatpak or use the system-wide package.

Creating Your First Container

Basic Container Creation

# Create an Ubuntu 24.04 container
distrobox create --name ubuntu-dev --image ubuntu:24.04

# Create a Fedora 41 container
distrobox create --name fedora-dev --image fedora:41

# Create a Rocky Linux 9 container
distrobox create --name rocky9 --image rockylinux:9

# Create an Arch Linux container
distrobox create --name arch-dev --image archlinux:latest

# List your containers
distrobox list

Using Specific Container Registries

# Pull from Quay.io
distrobox create --name rhel9 --image registry.access.redhat.com/ubi9/ubi

# Pull from GitHub Container Registry
distrobox create --name debian-testing --image ghcr.io/debian:testing

# Use a local image
distrobox create --name custom --image my-custom-image:latest

Container with Extra Configuration

# Container with additional volume mounts
distrobox create \
  --name dev-workspace \
  --image ubuntu:24.04 \
  --volume /opt/projects:/opt/projects:rw \
  --volume /data/databases:/data:ro

# Container with additional groups (useful for accessing devices)
distrobox create \
  --name hardware-dev \
  --image fedora:41 \
  --additional-packages "kernel-devel dkms"

Working Inside Distrobox Containers

Entering a Container

# Enter a container interactively
distrobox enter ubuntu-dev

# You are now inside Ubuntu 24.04
# Your home directory is available, your files are here
ls ~
whoami    # Shows your regular username, not root

# Install packages as you normally would
sudo apt update && sudo apt install -y golang nodejs python3-pip

Running Single Commands Without Entering

# Run a command in a container without entering it
distrobox enter ubuntu-dev -- apt list --installed 2>/dev/null

# Run a GUI application from the host terminal
distrobox enter fedora-dev -- firefox

# Run a script inside the container
distrobox enter rocky9 -- bash -c "yum check-update && yum update -y"

The Init Experience

The first time you run distrobox enter for a newly created container, Distrobox will spend a minute installing its init system and setting up your user account inside the container. This only happens once per container. Subsequent entries are fast.

Exporting Applications to the Host

One of Distrobox’s most powerful features is the ability to export applications — both command-line tools and GUI apps — so they are available directly from the host shell and application launcher without entering the container each time.

Exporting a Binary (CLI Tool)

# Inside the ubuntu-dev container, install a tool
distrobox enter ubuntu-dev
sudo apt install -y neovim

# Export it to the host (run this inside the container)
distrobox-export --bin /usr/bin/nvim --export-path ~/.local/bin

# Or run export from outside the container
distrobox enter ubuntu-dev -- distrobox-export --bin /usr/bin/nvim --export-path ~/.local/bin

# Now on the host system
nvim --version    # Works directly, transparently runs inside ubuntu-dev

Exporting a GUI Application

# Install a GUI app inside a container
distrobox enter ubuntu-dev -- sudo apt install -y gimp

# Export it (creates a .desktop file on the host)
distrobox enter ubuntu-dev -- distrobox-export --app gimp

# The app now appears in your system application launcher
# Launching Gimp from the host runs it inside the container automatically

Exporting Systemd Services

# Export a systemd service from the container to the host user session
distrobox enter ubuntu-dev -- distrobox-export --service syncthing

Real-World Use Cases

Development Environment Isolation

Keep different projects in separate containers with incompatible dependencies. A Python 3.9 data science project and a Python 3.12 web application can coexist without virtual environment conflicts because they live in entirely separate containers with their own system packages.

distrobox create --name python-datascience --image ubuntu:22.04
distrobox create --name python-webdev --image ubuntu:24.04

# Each has isolated system-level Python, pip, and packages
distrobox enter python-datascience -- python3 --version   # 3.10
distrobox enter python-webdev -- python3 --version        # 3.12

Testing Across Distributions

# Test your shell script on multiple distros simultaneously
for distro in ubuntu:22.04 ubuntu:24.04 fedora:40 fedora:41 rockylinux:9; do
    name=$(echo $distro | tr ':/' '--')
    distrobox create --name test-$name --image $distro --yes
    distrobox enter test-$name -- bash /path/to/your/script.sh
done

Immutable OS Compatibility

On Fedora Silverblue, Bazzite, or other atomic distributions, the host OS cannot be modified. Distrobox provides the traditional mutable environment you need for development work while keeping the atomic base intact.

centos-tools-on-ubuntu">Accessing RHEL/CentOS Tools on Ubuntu

# Get access to rpm, yum, dnf, and Red Hat tools on Ubuntu
distrobox create --name rhel-tools --image registry.access.redhat.com/ubi9/ubi-minimal
distrobox enter rhel-tools -- rpm -qa | wc -l

Distrobox vs Docker vs Toolbox vs Podman

Distrobox and Toolbox occupy the same niche, but Distrobox supports many more distributions, works with both Docker and Podman, and has more active development. Choose Docker or Podman directly when you need full container isolation for production services. Choose Distrobox when you want a transparent, integrated development or compatibility environment.

Advanced Usage and Configuration

Distroboxfile for Reproducible Containers

You can define containers declaratively in a distroboxfile, similar to how Dockerfile works for Docker images.

[distrobox]
name=my-dev-env
image=ubuntu:24.04
additional_packages=git vim curl wget build-essential nodejs npm
init=false
pull=true

# Create container from the file
distrobox assemble create --file distroboxfile

Stacking Containers with Host Application Access

# Access host binaries from inside a container
# The host's /usr is accessible at /run/host/usr inside the container
ls /run/host/usr/bin/

# Run a host binary from inside the container
/run/host/usr/bin/flatpak list

Managing Storage

# Check container disk usage
podman system df

# Remove a container you no longer need
distrobox rm ubuntu-dev

# Remove a container and its image
distrobox rm ubuntu-dev --force --rm-home

Troubleshooting Common Issues

Container Fails to Start After Host Update

# Recreate the container's init layer
distrobox enter my-container -- distrobox-init --verbose

# Or stop and delete, then recreate
distrobox stop my-container
distrobox rm my-container
distrobox create --name my-container --image ubuntu:24.04

GUI Applications Not Displaying

# Check DISPLAY is propagated
distrobox enter my-container -- echo $DISPLAY

# For Wayland sessions, check WAYLAND_DISPLAY
distrobox enter my-container -- echo $WAYLAND_DISPLAY

# If empty, create with explicit display flag
distrobox create --name gui-box --image ubuntu:24.04

Slow Performance on First Entry

The first entry into a container triggers initialization. This typically takes 30 to 90 seconds depending on image size and network speed for any missing packages. Subsequent entries start in under a second. If every entry is slow, check your container storage backend with podman info | grep -A5 store.

Home Directory Not Accessible

# Verify the home mount
distrobox enter my-container -- ls ~/

# If not accessible, check Podman version compatibility
podman --version   # Should be 3.4.0 or newer
distrobox --version

Conclusion

Distrobox bridges the gap between distribution fragmentation and the desire for a single, consistent host operating system. Whether you are on an immutable Fedora derivative that cannot install system packages, a stable Debian that does not have the latest Node.js, or simply need to test how your software behaves on a different distribution, Distrobox delivers a frictionless experience. The combination of transparent home directory access, GUI application support, and the ability to export applications back to the host makes it genuinely transparent in daily use. Start with a simple distrobox create and within minutes you have a fully functional parallel Linux environment at your fingertips.