Distrobox is a wrapper for docker and podman to create containers that are tightly integrated with the host: share the home directory, run graphical applications, external USB devices and more.

Table of Contents

Requirements and installation

Distrobox uses Podman (in rootless mode) or Docker (without sudo) to manage the containers. Ensure Podman or Docker can run without superuser privileges.

Distrobox is available on most distros (check https://github.com/89luca89/distrobox#installation). Use your system package manager to install distrobox.

Usage

Most Distrobox commands have two ‘versions’ (that work the same): one with distrobox and the command as argument, and other with distrobox, a hyphen and the command name, all without spaces:

distrobox create
distrobox-create

Create a container

To create a container, run distrobox create -i <image>, for example:

distrobox create -i debian
  • You can name the container with -n <name>.
  • The container is not started after creation.
  • Remember to use -i to specify the image name, this is different from Docker and Podman syntax.

Enter the container

To start (if it’s not already) and enter the container, run distrobox enter <container name>. The first time you run this command on a new container, this will configure the container to use the same username and $HOME folder as the host. This process also installs some Distrobox utilities. After initialization, you will be able to run commands inside the container.

Stop a container

Distroboxes keep running even when you exited them, so to stop a running container, execute:

distrobox stop <container name>

To start and enter into a stopped container, just use the distrobox enter <container name> command.

Remove a container

distrobox rm <container name>

List containers

distrobox list

Upgrade a container

This is an interesting command: you can upgrade the container packages from the host. Distrobox will perform the upgrade using the container package manager.

distrobox upgrade <container name>
  • -a: perform on all containers.

Running graphical apps

First, you need to grant your user access to the X screen, so the container can access to it without special privileges. To do this, run the following command on the host (as an ordinary user):

xhost +SI:localuser:$USER
  • If xhost is not installed, install x11-xserver-utils on Debian/Ubuntu or xorg-xhost on Arch Linux.

Then, you can enter on your container and install a graphical application, like Abiword, and run it.

Note: to set xhost to the default setting again (access control enabled), just run xhost -.

Export container apps to host

You can also access container apps directly from your host. Run this inside the container:

distrobox-export --app <app name>
  • Ensure to type distrobox-export and not distrobox export.

For example:

distrobox-export --app abiword

This will create a ‘.desktop’ file on your host, with a shortcut to:

distrobox enter <container name> -- <app name>

You will see the new item in your Programs Menu. The name of the menu item will be similar to this: ‘app-name (on container-name)’.

Distrobox

To ‘unexport’ an app (remove the shortcut), run the following command on the container:

distrobox-export --delete --app <app name>

Compatible container images

Check https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros for a list of compatible Distrobox guests.

If you have any suggestion, feel free to contact me via social media or email.