Mix and match Linux distributions with Distrobox

Linux containers have made it reasonably easy to develop, distribute, and deploy server applications along with all the distribution dependencies that they need. For example, anyone can deploy and run a Debian-based PostgreSQL container on a Fedora Linux host. Distrobox is a project that is designed to bring the cross-distribution compatibility to the desktop and allow users to mix-and-match Linux distributions without fussing with dual-booting, virtual machines, or multiple computers. It is an ideal way to install additional software on image-based systems, such as Fedora's Atomic Desktops or Bazzite, and also provides a convenient way to move a development environment or favorite applications to a new system.

Distrobox creator Luca Di Maio was inspired by the Toolbx project (formerly Container Toolbox) for Fedora. Generally, the idea with Linux containers is to run processes in their own environment to isolate them as much as possible from the host without having to resort to virtual machines with their additional overhead. It is possible, though, to set up a container to give it privileged access to the system with little to no isolation. This is typically referred to as a privileged container. It is possible to set up privileged containers manually, but it requires the user to know a great deal about working with containers and some fairly involved setup. The original goal for Toolbx was to let users run a privileged container "toolbox" on image-based systems that could be used for system administration and troubleshooting without having to include administration utilities in the image itself.

Toolbx has a somewhat limited scope: it works best with specific container images and was primarily developed to provide a software toolbox for image-based Fedora editions like CoreOS and Silverblue. Toolbx is also limited to the Podman container manager, which is not ideal for those who prefer to use Docker. Di Maio wanted to have broader compatibility with other Linux distributions as host operating systems as well as the ability to use a wide range of container images. He published the first release, Distrobox 1.0.0, in December 2021, under the GPLv3.

The Distrobox project is, as its homepage notes, "a fancy wrapper" that works with Docker and Podman, with di Maio's own minimal container manager, Lilipod, as a fallback if the others are not present. Distrobox is written in POSIX shell, so that it is as portable as possible. The project's primary goal is to allow the use of any Linux distribution containers on any Linux distribution host running one of the supported container managers. It also has a goal of entering a container as quickly as possible, "every millisecond adds up if you use the container as your default environment for your terminal".

Di Maio notes in the project's README that isolation and sandboxing of applications are non-goals: "on the contrary it aims to tightly integrate the container with the host". This means that containers run by Distrobox have access to the user's home directory, external storage, USB devices, audio devices, and more. The idea of a sandboxed mode for Distrobox was discussed but di Maio ultimately decided against implementing one and has opted not to take patches attempting to add isolation features: "the focus of distrobox is not isolation, security or stuff, but integration and transparency with the host".

Getting started

Distrobox is packaged for most popular Linux distributions, and the project has a compatibility table of host distributions for those it has been tested on. The table has notes with additional instructions if necessary. There is a table of guest distributions as well that lists the container images that have been successfully tested with Distrobox. If a distribution is not mentioned in the host or guest table it does not mean that Distrobox will not work; it simply indicates that the combinations have not been tested. Users will also need one of the supported container managers installed as well.

Here is an example of how and why one might use Distrobox: the Signal project only provides packages for Debian-based distributions, so there are no official packages for Arch, Fedora, openSUSE, or other non-Debian systems. There is a Flatpak available, but it is not maintained by the Signal project itself. It is possible to compile Signal from source, but it is far easier to create a Debian Distrobox and install the official Signal package there:

    $ distrobox create -i debian:trixie -n signal -H ~/distrobox/signal
    $ distrobox enter signal

The first command tells distrobox to create a new container using the debian:trixie image with its home directory set to ~/distrobox/signal, and to name it "signal". If the debian:trixie container image is not already present on the system, Distrobox will ask if you want to download it. Note that Distrobox uses the system's settings for short-name container lookup; it is also possible to pass the full registry path to distrobox if one prefers. The second command tells it to open a shell inside the container (or enter the container) so one can work within its environment.

All of that will probably look quite familiar to folks who work with Linux containers regularly, but Distrobox is doing quite a bit more behind the scenes. The "--dry-run" (or just "-d") option will print out the command that "distrobox create" is passing to the container manager for inspection, without taking any actions. It's worth eyeballing the output to see what goes into setting up a container that's well-integrated with the host system. In the case of the example command here, there are more than 50 options passed to podman, including 17 volume mounts. That is a lot of container magic that the user is not required to fuss with or know about, unless they want to.

One of the things it does is to set up passwordless sudo inside the container, so one can immediately install packages in the container and so forth. Note that, by default, Distrobox executes the user's login shell when entering a container, but this can be changed if one wants to use (say) the Fish shell on the host system but GNU Bash inside a Distrobox container.

The purpose of setting a home directory is not to provide isolation from the user's home directory, but to avoid clutter. If no home directory is specified, the guest container will use ~/; that may be undesirable if one wants to maintain a separate set of configuration files or project directories in a Distrobox. Applications and processes in the Distrobox will still be able to access files under the user's normal home directory. For example, if Distrobox container is set up with its home as /home/user/distrobox/signal then that will be set as $HOME for applications within the container. However, the applications can still access files in /home/user, /home/user/Documents, and so forth.

The distrobox create man page provides a number of useful examples to help getting started. The "distrobox create -C" command will provide a current list of images that are considered compatible with Distrobox. If a container image is not listed as compatible, that does not mean it won't work, just that it has not been tested and confirmed to work.

Naturally, Distroboxes can be destroyed as well as created: "distrobox rm name" will remove a container. That does not, however, remove the container image from the system. If the goal is to completely purge the container image as well, then it's necessary to use the container manager to do so, e.g. "podman rmi imagename".

Exporting applications and moving containers

Since Distrobox is often used to run desktop applications, it does not make sense to have to enter the Distrobox container each time one wants to run Signal or some other application. The project provides a distrobox-export command that sets up a .desktop file to launch the command directly from one's desktop. For example, this will create a launcher for the Signal desktop client:

    $ distrobox-export --app signal-desktop

Note that the command should be run from within the container created by Distrobox, not on the host. Assuming that the user is running a desktop environment like GNOME, KDE, or Xfce, an entry for Signal should show up in whatever menu or launcher is being used. Now it's not necessary to use "distrobox enter" at all to run Signal, it can be run like any other desktop application that is installed on the host. Even though Distrobox prioritizes speed in starting containers, there is usually a small but noticeable lag when launching an application from a container that hasn't started yet.

Alternatively, one might want to use a Distrobox container as their primary command-line environment. Some terminal emulators, such as Ptyxis, offer integration with Distrobox and other container tools; a user can set Ptyxis to open new terminal windows in the container automatically. This is particularly handy on image-based systems where one cannot install software directly on the host using APT or DNF. I set Ptyxis to use a Fedora container by default and do my work in the container and install additional software therein. To distinguish between working in the host terminal and in my default container, I set the color palette to "Borland" from the Gogh set of color schemes for terminals. The old-school look is appealing, and I don't get it confused with the black-on-green theme for regular terminals.

The "distrobox assemble" command can automate the creation of one or more Distroboxes. It takes an INI file with specifications on how to create a new container or multiple containers. For example, this is a simple distrobox.ini that would create a container using a Fedora Rawhide image with several packages that I use regularly. The pull=true option tells distrobox to go ahead and pull the container image if it is not available on the system.

    [rawhide]
    additional_packages="emacs emacs-pgtk aerc tmux git lolcat bat"
    image=fedora:rawhide
    pull=true
    home=/home/jzb/distrobox/rawhide

Jorge Castro has written a good blog post on using "distrobox assemble" that is worth reading for anyone using Distrobox.

The project is not on a time-based schedule, so releases are somewhat sporadic. There is also no roadmap to follow for future releases. Generally, Distrobox seems mostly feature complete, so new versions seem to be mostly about bug fixes or catching up to changes in Linux distributions and container tooling. The most recent feature release was version 1.8.2.0 on October 28 which included Bash completion enhancements, added support for new guest distributions, and included quite a few documentation changes as well as bug fixes. With that release, di Maio also announced the addition of Alessio Biancalana as a maintainer, and Biancalana has headed up the recent minor releases. The most recent is 1.8.2.2.

The project does not, unfortunately, have a mailing list or even a web forum: the documentation points users to a Matrix room and Telegram group instead. Users interested in making contributions or reporting bugs should check CONTRIBUTING.md for guidance.

I've found Distrobox to be enormously useful for providing an easy and quick way to run multiple distributions on a single system. Distrobox is probably one of my most-used applications after Firefox and Emacs. Multiple versions of Alpine Linux, CentOS Stream, Debian, Fedora, openSUSE, Ubuntu, and others are just a few keystrokes away any time I need them.