distrobox

View documentation for creating containers

$ tldr distrobox-create

$ tldr distrobox-list

$ tldr distrobox-enter

$ tldr distrobox-host-exec

$ tldr distrobox-export

$ tldr distrobox-upgrade

$ tldr distrobox-stop

$ tldr distrobox-rm

distrobox [GLOBAL_OPTIONS] SUBCOMMAND [SUBCOMMAND_OPTIONS] [ARGUMENTS]

Common Subcommands:
distrobox create [OPTIONS] CONTAINER_NAME
distrobox enter [OPTIONS] CONTAINER_NAME [COMMAND]
distrobox list
distrobox rm CONTAINER_NAME [...]
distrobox upgrade

-h, --help
    Display help message for distrobox or a subcommand.

--root
    Run distrobox as root (using sudo/doas).

create
    Create a new distrobox container.

-i, --image
    Specify the container image to use (e.g., fedora:latest, ubuntu:22.04).

-n, --name
    Specify the name for the new container.

--home
    Mount a custom host path as the container's home directory.

--volume
    Mount an additional host path into the container (e.g., /opt/mydata:/mnt/data).

--pull
    Force pull the container image, even if it exists locally.

--yes
    Automatically answer yes to prompts during creation.

enter
    Enter a distrobox container to execute commands or a shell.

-n, --name
    Specify the name of the container to enter.

[COMMAND]
    Command to execute inside the container instead of the default shell.

list
    List all created distrobox containers.

rm
    Remove one or more distrobox containers.

stop
    Stop one or more running distrobox containers.

upgrade
    Upgrade all distrobox containers to their latest configuration/image.

export
    Export an application from a container to the host system's PATH and menu entries.

distrobox is a command-line utility that leverages container runtimes like Podman or Docker to create isolated yet deeply integrated Linux environments. It allows users to create containers running different Linux distributions (e.g., Fedora, Debian, Arch, Ubuntu, openSUSE) and seamlessly integrate them with the host system. This means applications installed inside a distrobox container can access the host's home directory, display server (X11/Wayland), audio (PulseAudio/PipeWire), network, and other resources as if they were natively installed. This makes it ideal for development, testing, and running software that might conflict with the host's package versions or dependencies, especially on immutable operating systems. It provides a simple way to manage multiple isolated user spaces without the overhead of virtual machines, enabling a flexible and consistent cross-distribution workflow.

Requires podman or docker to be installed on the host system. While providing deep integration, distrobox containers share the host's Linux kernel, meaning they are not full virtual machines and cannot run different kernel versions or load arbitrary kernel modules. Performance can vary depending on the container runtime and host system resources. Certain specialized networking configurations might require additional setup.

distrobox functions by creating OCI-compliant containers (using podman or docker) from chosen Linux distribution images. It then performs various bind mounts and configurations to seamlessly integrate the container with the host system. This includes mounting the host's /home, /etc/passwd, /etc/group, and various X11/Wayland and audio sockets, allowing GUI applications to run directly from within the container and appear as native host applications.

Cross-Distribution Compatibility: Run applications and development environments from any supported Linux distribution on your host.
Immutable Host Friendliness: Provides a mutable user space on immutable host systems (e.g., Fedora Silverblue, openSUSE MicroOS) without modifying the base OS.
Seamless Integration: Applications installed in a distrobox container can access the host's home directory, display, sound, and other resources.
Isolated Environments: Keep dependencies and software conflicts isolated within containers, preventing 'dependency hell' on the host.
Resource Efficiency: Lighter than full virtual machines, sharing the host kernel and consuming fewer resources.

Developed by Luca Di Maio (86Simone) and first publicly released around early 2022. The project was motivated by the need for a generic, cross-distribution solution for creating development and testing environments, especially on immutable host operating systems where traditional package management is discouraged. It aimed to provide a more flexible alternative to Fedora's toolbox utility. Since its inception, distrobox has seen rapid adoption and active development, quickly becoming a popular tool for containerized workflows on Linux.

podman(1), docker(1), toolbox(1), chroot(1), systemd-nspawn(1)