Distrobox is a free and open source tool which allows us to integrate the userlands of Linux distributions. Under the hood it uses Docker or Podman to create containers, and integrates them with the host by sharing access to the graphical server, the user HOME directory and USB devices. In this tutorial we see how to install and use Distrobox on the most used Linux distributions.
In this tutorial you will learn:
- How to install Distrobox on the most used Linux distributions
- How to integrate a distribution using Distrobox
- How to enter and use a Distrobox container
- How to export applications from a container
- How to list, stop and remove existing containers
| Category | Requirements, Conventions or Software Version Used |
|---|---|
| System | Distribution-agnostic |
| Software | Distrobox, Podman or Docker |
| Other | None |
| Conventions | # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command$ – requires given linux-commands to be executed as a regular non-privileged user |
Introduction
Distrobox works similarly to toolbox, but it is compatible with a wider range of distributions (you can find the actual list on GitHub), and can use both Podman and Docker under the hood, while toolbox supports only the former. Distrobox aims at achieving a seamless integration of containers with the host system: the graphical stack, the user HOME directory and USB storage devices are indeed shared, by default, with containers. For this reason, if isolation and security are primary goals, Distrobox is not the appropriate tool.
Installation
All the most used Linux distributions include Distrobox in their official repositories, therefore installing it is just a matter of using the appropriate package manager. Here is the exact commands we want to use:
| Debian/Debian-based | $ sudo apt install distrobox |
| Fedora | $ sudo dnf install distrobox |
| Archlinux | $ sudo pacman -S distrobox |
Getting started
The most basic way to create and integrate a distribution with Distrobox, is by using the create command without any option or argument:
$ distrobox create
When invoked this way, Distrobox creates a container using the default image, which is specified via the
container_image_default variable in the Distrobox configuration file; this, most of the time, equals to the host distribution. To use a specific distro (and optionally a release version) as a target, we pass its name as argument to the -i option (short for --image). To create a container based on Archlinux, for example, we would run:
$ distrobox create -i archlinux
If the image of the target distribution doesn’t exist locally, Distrobox will ask us if we want to download it:
Image archlinux not found. Do you want to pull the image now? [Y/n]: y
To avoid interactive prompts like the one above, we can add the -Y (--yes) option to the command. Once the download is complete, Distrobox will create a container based on the image, naming it, by default, after the distribution itself (we can specify an alternative name with the -n option).
When creating a container, we have the chance to specify a list of extra packages which should be installed, using the --additional-packages option. In the example below, we create a container based on Archlinux, and specify we want to install the git and vim packages:
$ distrobox create -i archlinux --additional-packages "vim git"
Specifying an alternative HOME for the container
As we already said, containers created with Distrobox, share the HOME directory with the user launching Distrobox commands. This means that a program running inside the container, may clutter it with its own configuration files. To avoid this, we can specify an alternative HOME for the container, using the -H (--home) option. Here is an example:
$ distrobox create -i archlinux -H ~/container-home
The target directory will be automatically created if it doesn’t exist.
Entering the container
Once a container is ready, to begin using it, we use the enter command, passing its name as argument. To enter a container named “archlinux”, we would run:
$ distrobox enter archlinux
The first time we enter a container, Distrobox performs some preliminary operations. Once the container setup is complete, the shell prompt will change, to reflect the fact that we are working in the container environment:
📦[doc@archlinux ~]$
We can now execute commands just as if we were using the system natively. Since in this case the target distribution is Archlinux, to synchronize repositories, we would run:
📦[doc@archlinux ~]$ sudo pacman -Sy
Since the container has access to the host system graphical stack, we can install and use both command line and graphical applications in it. To install “code” (the open source version of the VScode editor), for example, we would run:
📦[doc@debian-bullseye ~]$ sudo pacman -S code
Once the application is installed, we can launch it from the command line:
📦[doc@archlinux ~]$ code
As an alternative to manually entering the container each time we want to run a command inside of it, we can use the following shortcut:
$ distrobox enter archlinux -- code
Exporting an application
In the previous example, we saw how easy it is to install and launch an application inside a container created with Distrobox. To better integrate an application in the host system, however, we can “export” it.
In the previous example we installed the “code” editor, but we were forced to run it from the command line, since the desktop launcher didn’t appear in the “applications” menu of the host system. To solve this problem, we can “export” the application with the distrobox-export command, which must be executed inside the container.
To export the “code” editor, we would run:
$ distrobox enter archlinux -- distrobox-export --app code
After a few seconds, we should find the application launcher in the host menu:
To undo the export of an application, we add the --delete option to the distrobox-export command. To delete the “code” launcher from the host system, we would run:
$ distrobox enter archlinux -- distrobox-export --app code --delete
Managing distrobox containers
To list containers created with Distrobox we can use the list command:
$ distrobox list
In this case, as expected, only one container exists:
ID | NAME | STATUS | IMAGE 1989f0686c1f | archlinux | Up 29 minutes | docker.io/library/archlinux:latest
As we can see from the output of the command, the container is currently running. In order to stop it, we use the
stop command:
$ distrobox stop archlinux
Finally, to remove the container, we use the rm command:
$ distrobox rm archlinux
Conclusions
Distrobox is a free and open source application which allow us to integrate a host system with the userland of supported Linux distributions, using containers and relying on Docker or Podman under the hood. In this tutorial we saw how to install Distrobox on some of the most used Linux distributions, how to create and enter containers, and how to run commands inside of them. We also saw how to export containers applications to the host system, and, finally, how to list, stop and remove containers created with Distrobox.