Skip to content

Setting Up a Toolbox

When you want to install applications not required on your base system and not available as Flatpaks, you can use a "toolbox" program. Toolbox programs run OS containers using Podman allowing you to enter into the containers' command line interfaces and use them transparently with access to files in your home directory. For example, you could have one toolbox where all of your software development-related packages and programs live.

Toolboxes don't require as much maintenance as running the distribution on bare metal, and you can very easily have multiple side-by-side, remove existing ones, and replace them with new entirely fresh ones.

Fedora comes with toolbx and the Universal Blue images come with both toolbx and distrobox, but this page will only cover distrobox.

Creating and using a Distrobox

To create a Fedora 38 Distrobox, run:

distrobox create --image --name fedora

To create an Ubuntu 22.04 Distrobox, run:

distrobox create --image --name ubuntu

To create an Arch Linux Distrobox, run:

distrobox create --image --name arch

List of tested container images.

When choosing an image for your container, consider which package manager and repos you want to use (e.g. apt vs. pacman), and pick one that you're most comfortable with!

Once you've created your Distrobox, you can enter it by running:

distrobox enter <boxname>

Now you have access to everything installed within the Distrobox and can install new packages using its package manager.

Read more in the Distrobox documentation or GitHub repository.

Exporting programs from Distrobox

You can export a GUI program (for example, mpv) by running the following from inside the Distrobox:

distrobox-export --app mpv

You can also export a binary or CLI program (for example, vim) by running the following from inside the Distrobox. You need to provide an export path and know where the original binary exists in the Distrobox's filesystem. An easy way to find out is running which vim (replace vim with the name of the binary you want to export). The export command will create a shell script that runs the specified binary from inside the Distrobox.

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

Read more in the Distrobox documentation about distrobox-export

Integrating VSCode with Distrobox

There are two ways to integrate VSCode with a Distrobox.
The easiest way is to just install it inside your Distrobox and distrobox-export it. The integrated terminal and all addons will then be run inside that single Distrobox. The other way is with the Dev Containers extension. Both ways are detailed inside the official Distrobox tutorial for integrating with VSCode

Using the host's xdg-open inside Distrobox

Some GUI programs use xdg-open to open URLs, but it doesn't work when running your browser on the host. You can fix this by adding the following shell script to your ~/.local/bin/ and giving it executable permissions.

if [ ! -e /run/.containerenv ] && [ ! -e /.dockerenv ]; then # if not inside a container
    /usr/bin/xdg-open "$@" # run xdg-open normally
    distrobox-host-exec /usr/bin/xdg-open "$@" # run xdg-open on the host

If you have xdg-open installed inside the Distrobox, you need to make sure that ~/.local/bin/ is in your $PATH before /usr/bin/.