How to Install and Use Distrobox in Linux to Run Any Distribution Inside Your Terminal

Modern Linux workflows frequently require tools, libraries, or package formats that are native to another distribution. While container engines like Docker and Podman provide isolated runtime environments, they run detached from your host desktop, user accounts, graphical sessions, and home directories. Distrobox solves this challenge by leveraging Podman or Docker to create tightly integrated, mutable container environments that share your user namespace, home folder, audio devices, and Wayland or X11 graphical sessions. This guide explains how to install and utilise Distrobox in Linux to execute and manage any Linux distribution directly within your native terminal.

Understanding How Distrobox Operates

Distrobox does not attempt to be an application sandbox or a virtualisation hypervisor. Instead, it creates standard Open Container Initiative (OCI) containers and applies specialised mount namespaces and configuration overlays so that the guest container behaves almost indistinguishably from your host system:

• Shared Home Directory: Your host $HOME directory is mounted directly into the container, meaning your configuration files, source code, and user assets remain instantly accessible without copying files.
• Display and Audio Forwarding: Wayland sockets, X11 sockets, PipeWire, and PulseAudio are mapped automatically, allowing graphical applications installed inside Distrobox to appear on your host desktop.
• Removable Media and Peripheral Access: Storage drives under /media and /mnt, system logs under /var/log, and hardware devices (such as USB devices and GPUs) are bridged automatically.
• Zero Sudo Host Requirement: When paired with rootless Podman, Distrobox containers execute entirely within your unprivileged user account, preserving host stability.

Prerequisites and Container Engine Setup

Distrobox requires an underlying container manager. While Docker is supported, Podman is the strongly recommended default because of its native rootless design and integration with Linux user namespaces.

To install Podman on Ubuntu, Debian, or Linux Mint, open your terminal and run:

sudo apt update && sudo apt install -y podman

To install Podman on Fedora or AlmaLinux:

sudo dnf install -y podman

To install Podman on Arch Linux:

sudo pacman -S podman

Verify that your rootless container subsystem functions correctly by executing:

podman info

Installing Distrobox on Linux

Most major distributions offer Distrobox in their official repositories. Alternatively, an official curl-based installer is provided for distributions running immutable or older system trees.

Method 1: Installing via Native Package Managers

On Ubuntu 22.10 and newer, or Debian 12 (Bookworm):

sudo apt install -y distrobox

On Fedora 36 and newer:

sudo dnf install -y distrobox

On Arch Linux:

sudo pacman -S distrobox

Method 2: Installing via the Official Script (For All Systems)

If your distribution lacks an updated package, run the official installation script directly into your user path or system directories:

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

Verify the installation by querying the active version:

distrobox --version

Creating and Initialising Your First Distrobox Container

Distrobox uses the create command to pull container images and set up the integration layer. You can specify custom container names and target images from Docker Hub, Quay, or GitHub Container Registry.

Creating an Arch Linux Container on an Ubuntu or Fedora Host

To create an Arch Linux environment named arch-dev, run:

distrobox create --name arch-dev --image docker.io/library/archlinux:latest

Creating an Ubuntu or Fedora Development Environment

To spin up an Ubuntu 24.04 LTS container:

distrobox create --name ubuntu-box --image docker.io/library/ubuntu:24.04

To create a container using Fedora Rawhide or Alpine Linux:

distrobox create --name alpine-tools --image docker.io/library/alpine:latest

Entering and Managing the Distrobox Environment

Once created, access the container using the enter command:

distrobox enter arch-dev

During the very first launch, Distrobox performs an initialisation sequence. It downloads essential integration packages, creates user mappings, and mounts system pipes. This initialisation typically takes 30 to 60 seconds depending on your network connection.

Once initialised, your shell prompt will reflect the container hostname, yet running ls ~ displays all files from your host home directory. You can now use the native package manager of that distribution without affecting your host operating system:

sudo pacman -Syu
sudo pacman -S neovim git htop

To exit back to your host terminal, simply type:

exit

Exporting Applications and Binaries to Your Host System

One of the most powerful features of Distrobox is the ability to export graphical applications and terminal binaries directly into your host distribution’s application menu and command search path.

Exporting Graphical Applications

If you install a GUI tool inside your container (for example, the GIMP image editor or an IDE inside an Arch container), you can export its desktop entry to your host desktop environment:

1. Enter your container:

   distrobox enter arch-dev

2. Install the required graphical application:

   sudo pacman -S gimp

3. Export the desktop shortcut to your host system:

   distrobox-export --app gimp

The application icon immediately appears in your GNOME Shell, KDE Plasma, or XFCE launcher menu. Launching it runs the software inside the container while drawing windows directly on your host desktop.

Exporting Command-Line Binaries

To run a binary installed inside a Distrobox container directly from your host shell without explicitly typing distrobox enter, use the binary export flag:

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

Ensure ~/.local/bin is in your host shell’s $PATH. You can now execute the containerised utility seamlessly from any host terminal session.

Container Lifecycle and Maintenance

Managing your collection of Distrobox environments is straightforward with built-in commands:

Listing Active and Inactive Containers

distrobox list

This command outputs a formatted table showing container names, container IDs, status, base image, and whether the container is currently running.

Stopping and Removing Containers

To halt an active container and free system memory:

distrobox stop arch-dev

To completely delete a container that is no longer required:

distrobox rm arch-dev

Add the -f flag to bypass confirmation prompts if automating cleanup scripts.

Advanced Customisation and Persistent Workflows

For advanced development setups, Distrobox supports mounting additional host directories and granting root privileges:

• Rootful Containers: If you need to perform deep hardware diagnostics or system-level testing, append the --root flag during creation:

  distrobox create --name debian-root --image docker.io/library/debian:12 --root

• Custom Home Directories: To keep container experiments isolated from your main host configuration files, specify an alternative home directory:

  distrobox create --name isolated-node --image node:20 --home ~/containers/node-home

• Automated Upgrades: Keep all software inside every configured container up to date with a single command on your host:

  distrobox-upgrade --all