The model

Distrobox uses Podman (preferred) or Docker as the container runtime. Each "distrobox" is one container based on a distro image, configured with:

  • Your $HOME bind-mounted at the same path.
  • User UID / GID match (no permission issues writing to $HOME).
  • DBus, PulseAudio / PipeWire, X11 / Wayland sockets passed through — GUI apps render to the host display.
  • Network shared with the host.
  • Same /tmp.

Inside the container, you can install packages with that distro's package manager, run shells, run GUI apps. The host stays unmodified.

Install

# Distrobox itself (a shell script wrapper around podman/docker)
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sudo sh

# Or via package manager
sudo apt install distrobox podman             # Debian / Ubuntu
sudo dnf install distrobox                    # Fedora (Silverblue / Workstation)
sudo pacman -S distrobox                      # Arch

# Verify
distrobox version
podman version              # or docker version

Create your first distrobox

# An Arch container on, say, a Debian host
distrobox create --name arch --image quay.io/toolbx/arch-toolbox:latest

# Enter it
distrobox enter arch

# Inside, run pacman as if you were on Arch
sudo pacman -Syu
sudo pacman -S yt-dlp ffmpeg cmake

# Exit back to host
exit

First create downloads the image; subsequent enters are instant. The container persists across sessions; "exiting" doesn't destroy it.

Common images

# Distrobox-recommended images (with pre-installed user-side tools)
distrobox create --name fedora      --image registry.fedoraproject.org/fedora-toolbox:41
distrobox create --name ubuntu      --image quay.io/toolbx/ubuntu-toolbox:24.04
distrobox create --name debian      --image quay.io/toolbx/debian-toolbox:12
distrobox create --name alpine      --image docker.io/library/alpine:latest
distrobox create --name centos      --image quay.io/centos/centos:stream9
distrobox create --name opensuse    --image registry.opensuse.org/opensuse/distrobox:latest
distrobox create --name nix         --image docker.io/nixos/nix:latest
distrobox create --name kali        --image docker.io/kalilinux/kali-rolling:latest

Almost any base distro image works; the "toolbox" / "distrobox" tagged ones bundle the small helpers Distrobox uses for seamless integration.

Export an app to the host

Run a GUI app inside the container and pin it to the host's app launcher:

# Inside the distrobox
sudo apt install firefox-esr
distrobox-export --app firefox-esr

A Firefox launcher appears in the host's app menu; clicking it transparently runs Firefox inside the Debian distrobox, with windows on the host's display. Same trick works for CLI tools:

distrobox-export --bin /usr/bin/some-cli --export-path ~/.local/bin
# Now `some-cli` from host shell silently runs inside the distrobox

Reproducible distrobox via init-hooks

For "every time I (re)create my Fedora distrobox, install these packages":

# ~/.config/distrobox/fedora.ini  (or as cli args)
[fedora]
image=registry.fedoraproject.org/fedora-toolbox:41
init_hooks=sudo dnf install -y ripgrep fd-find bat eza zoxide fzf gcc-c++ cmake

# Then
distrobox-assemble create --file ~/.config/distrobox/fedora.ini

The container is created with those packages installed; deleting and recreating gives the same environment.

Common use cases

  • Atomic-distro users (Fedora Silverblue, openSUSE MicroOS, Bazzite, Aurora) — the host filesystem is immutable; everything dev-related happens inside a distrobox.
  • Test installs of different distros without VMs — quick "does this work on Alpine?" without spinning up a separate machine.
  • Old / EOL tooling — pin a CentOS 7 distrobox for a vendor build chain that requires it; the host stays modern.
  • NixOS host running non-Nix apps — NixOS's strict environment confuses some prebuilt binaries; a Debian distrobox runs them happily.
  • Polyglot dev — one distrobox per language ecosystem keeps tool versions isolated without affecting the host.

Distrobox vs Toolbx vs nix-shell vs Docker

  • Toolbx (Fedora's tool) — predecessor to Distrobox; Fedora-focused; less polished for non-Fedora hosts. Distrobox is the more portable evolution.
  • nix-shell / devbox — reproducible dev environments via Nix; different mental model (declarative, atomic) but no full distro userspace.
  • Plain Docker — isolated; you have to mount $HOME, fix UIDs, pass through display sockets yourself. Distrobox is "Docker plus the integration scripts you'd have written."
  • VM (GNOME Boxes, virt-manager) — full isolation; no $HOME passthrough; more overhead.

When Distrobox isn't the right tool

  • For full isolation (you don't want the container to see your $HOME), use plain Podman / Docker with explicit volumes.
  • For headless server workloads, just use the container runtime directly — Distrobox's display passthrough adds nothing.
  • For "I need a different kernel," only a VM gives you that; containers share the host kernel.

For "I want this distro's package manager, in a way that doesn't make me commit to that distro on the host," Distrobox is the right size in 2026.