Use distrobox to Run Other Distros in Containers

Distrobox wraps podman or docker to give you fully mutable, home-directory-integrated containers that behave like a second distro living inside your current one. You get Arch's AUR, Fedora's RPMs, or Debian's .deb packages on any host—without dual-boot, without VMs, and without polluting your host system. The host's $HOME, display server (X11 or Wayland), PulseAudio/PipeWire, and D-Bus sockets are all shared automatically.

Prerequisites and Installation

Distrobox needs either podman (recommended, rootless by default) or docker on the host. Podman 3.0+ is sufficient; podman 4.x is preferred.

Install Podman

# Debian / Ubuntu
sudo apt install podman

# Fedora / RHEL 9+ / Rocky 9+
sudo dnf install podman

# Arch
sudo pacman -S podman

Install Distrobox

Many distros now ship distrobox in their repos, but the upstream script always gives you the latest release.

# Package manager (when version is recent enough)
# Debian/Ubuntu 23.04+
sudo apt install distrobox

# Fedora 37+
sudo dnf install distrobox

# Arch
sudo pacman -S distrobox

# Upstream installer — installs to ~/.local/bin, no root needed
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --prefix ~/.local

After the upstream install, make sure ~/.local/bin is in your $PATH. Add the following to ~/.bashrc or ~/.zshrc if it isn't already:

export PATH="$HOME/.local/bin:$PATH"

Creating Your First Box

distrobox create pulls a container image and registers it. The --image flag accepts any OCI image—use the image names from the compatibility list for guaranteed support.

# Fedora 40 box
distrobox create --name fedora40 --image fedora:40

# Ubuntu 24.04 box
distrobox create --name ubuntu-noble --image ubuntu:24.04

# Arch Linux box
distrobox create --name arch --image archlinux:latest

# openSUSE Tumbleweed
distrobox create --name tumbleweed --image opensuse/tumbleweed

First-time creation downloads the image and runs first-boot setup (installs a minimal set of packages inside the container so distrobox integration works). This takes a minute or two; subsequent starts are near-instant.

List and Enter Boxes

# Show all boxes and their status
distrobox list

# Enter a box (starts it if stopped)
distrobox enter fedora40

You land in a shell inside the container with your same username, the same $HOME, and the container's package manager available. Your host files are immediately visible.

Installing Packages Inside a Box

Once inside, use the distro's native package manager as you would on a real install:

# Inside the fedora40 box
sudo dnf install gcc make strace

# Inside ubuntu-noble
sudo apt update && sudo apt install build-essential

# Inside arch
sudo pacman -Syu && sudo pacman -S base-devel yay

The sudo inside a distrobox container is passwordless for your user by default—it's scoped to the container and does not affect your host.

Exporting Apps and Commands to the Host

distrobox-export creates host-side wrapper scripts or .desktop entries so you can run container binaries directly from your host shell or application launcher—no need to enter the box first.

Export a CLI Binary

# Run this INSIDE the box
distrobox-export --bin /usr/bin/htop --export-path ~/.local/bin

Now typing htop on the host runs the container's version transparently.

Export a GUI Application

# Inside the fedora40 box — export a .desktop entry to the host
distrobox-export --app firefox

The .desktop file lands in ~/.local/share/applications/ and appears in your application launcher. Wayland and X11 sockets are forwarded automatically, so the app displays on your host session without extra configuration.

Run a One-Off Command Without Entering

# From the host, run a command directly in a named box
distrobox enter --name fedora40 -- dnf list installed | grep python

Init Hooks: Automate Box Setup

An init hook is a script that runs inside the container on first creation, letting you automate package installation and configuration so the box is ready to use immediately—no manual setup after distrobox create.

Writing a Hook Script

cat > ~/dotfiles/distrobox/fedora-dev-init.sh << 'EOF'
#!/bin/bash
set -e

# System packages
sudo dnf install -y \
    gcc gcc-c++ make cmake git \
    python3 python3-pip nodejs npm \
    neovim ripgrep fd-find

# User-level setup
pip3 install --user black isort

echo "fedora40 dev box ready."
EOF
chmod +x ~/dotfiles/distrobox/fedora-dev-init.sh

Attaching the Hook at Creation

distrobox create \
  --name fedora-dev \
  --image fedora:40 \
  --init-hooks ~/dotfiles/distrobox/fedora-dev-init.sh

The hook runs once when the box is first initialised. You can pass multiple --init-hooks flags; they execute in order. Hooks are re-run if you delete and recreate the box, making them a lightweight form of declarative box configuration.

Integration with the Host Shell

Beyond exporting individual binaries, distrobox can inject an entire container environment into your host shell session using distrobox-enter combined with shell aliases, or via the --additional-flags podman argument for volume mounts.

Shell Aliases for Fast Switching

# Add to ~/.bashrc or ~/.zshrc
alias in-fedora='distrobox enter fedora40 --'
alias in-arch='distrobox enter arch --'

# Use like any shell prefix
in-fedora rpm -qa | grep curl
in-arch yay -Ss spotify

Mounting Extra Host Paths

By default only $HOME is mounted. For project directories outside $HOME (e.g. /srv/projects), pass additional volumes at creation time:

distrobox create \
  --name build-box \
  --image ubuntu:24.04 \
  --volume /srv/projects:/srv/projects:rw

Using Systemd Inside a Box

Some images (Fedora, openSUSE) support running systemd as PID 1 inside the container. Add --init --additional-flags '--systemd=always' at create time. This is useful for testing services, but most development workflows don't need it.

Managing Box Lifecycle

# Stop a running box
distrobox stop fedora40

# Remove a box (container only — your home files are untouched)
distrobox rm fedora40

# Remove and re-create cleanly
distrobox rm fedora40 && distrobox create --name fedora40 --image fedora:40

The underlying container image stays cached in podman. To free disk space, prune unused images separately:

podman image prune -a

Verification

# Confirm distrobox version
distrobox version

# List boxes and check STATUS column shows "Up" after entering
distrobox list

# Verify host integration — run from the HOST after exporting htop
which htop          # should resolve to ~/.local/bin/htop
cat ~/.local/bin/htop  # shows the distrobox wrapper script

Troubleshooting

• Box creation hangs or fails to pull image: Check your network and that podman itself can pull: podman pull fedora:40. On some corporate proxies you need HTTP_PROXY / HTTPS_PROXY set in your environment.
• GUI apps don't appear on Wayland: Ensure $WAYLAND_DISPLAY is set in your host session. Distrobox forwards it automatically, but if you launched the terminal over SSH it may be missing.
• "Permission denied" on /run/user/1000/ sockets: Your UID inside the container must match the host. Distrobox handles this automatically with podman's user namespace mapping; if it doesn't, confirm /etc/subuid and /etc/subgid include your user.
• Exported binary not found on host: Confirm ~/.local/bin is in $PATH and that you re-sourced your shell config after adding it (source ~/.bashrc).
• Init hook didn't run: Hooks only fire on first initialisation. If the box already exists, remove it with distrobox rm first, then recreate.