Getting started with Toolbx

Fedora Silverblue is an immutable variant of Fedora Workstation: every installation of this distribution is identical to the others, which is ideal for testing and predictability. On Fedora Silverblue, flatpaks are used as the primary method of installing software together with rpm-ostree which basically creates an additional layer over the immutable filesystem each time an rpm is installed. The toolbx utility is included in Fedora Silverblue as a way to create isolated, mutable environments using podman and the containers technology, allowing the user to install development tools and libraries without touching the main system. Toolbx can be used also on regular Fedora versions.

In this tutorial we learn how to use Toolbx and Podman to create interactive containers we can use to install applications, libraries and development tools.

In this tutorial you will learn:

  • How to install the Toolbox utility
  • How to create containers based on supported systems and custom images
  • How to list toolbx containers
  • How to spawn interactive shells inside toolbx containers
  • How to remove toolbx container and images
Getting started with toolbx
Getting started with Toolbx


Software Requirements and Linux Command Line Conventions
Category Requirements, Conventions or Software Version Used
System Distribution-independent
Software Toolbx, podman
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


The Toolbx utility was originally meant to work in the Red Hat ecosystem, but it can easily be installed on other distributions, such as Ubuntu or Archlinux. Fedora Silverblue comes with Toolbox installed by default and the package is also included in the official Fedora Workstation package set, however, if required, we can install it explicitly by using the dnf package manager:

$ sudo dnf install toolbox

[ADLSOT1]On recent Ubuntu versions, the package is called “podman-toolbox”. To install it, we can use the following command:

$ sudo apt-get install podman-toolbox

Unfortunately, at the time of writing, Toolbox is available only in the Debian unstable branch (Sid), therefore if you need to use it on the stable branch, you will need to backport it.

Toolbx is also available in the Archlinux “Extra” repository, from which it can be installed using pacman:

$ sudo pacman -S toolbox

Creating toolbox containers

Once Toolbx is installed on our system, we can create our first environment. In order to do that we invoke the toolbox utility, and the create subcommand. Toolbx containers are designed to integrate with the host system, so they have access, among the other things, to the display server, the user home directory, removable devices, and the network.

If a container is created without specifying any argument, and the host system is among the supported ones (Only Fedora and RHEL), an image corresponding to the host system is used as a base for it, otherwise the Fedora image is used as a fallback. If the image on which the container will be based doesn’t exist on our system, we will be prompted to confirm we want to download it:

$ toolbox create
Image required to create toolbox container.
Download (500MB)? [y/N]:

I am currently running on the latest release of Fedora Workstation. As you can see in the output of the command above, the corresponding image is downloaded. By default a container is named after the image it is based on, however we can specify a name as the last argument to the create subcommand:

$ toolbox create mycontainer

If we want to create a container based on a distribution different from the one we are using for the host system, we have basically two options. The first one consists into using the --distro and --release options, to specify one of the supported images (again, Fedora and RHEL >= 8.5) and a specific release. To explicitly create a container based on Red Hat Enterprise Linux 9.1, for example, we would run:

$ toolbox create --distro rhel --version 9.1

The other, more flexible way to create a container based on a system of our choice, is to use --image option and provide the path of the container image we want to use. Some community-maintained images are developed on github and are hosted on the register. Just as an example, to create a container based on the Archlinux image, we would run:

$ toolbox create --image

To retrieve the list of the toolbox container we created and the images they are based on, we can use the list sub-command:

$ toolbox list

From the output of the command above you can see I have created three containers:

fbbcbb096255 archlinux-toolbox-latest 23 minutes ago created
71e7acb61e86 fedora-toolbox-38 45 minutes ago running
3d7b9594a559 rhel-toolbox-9.1 5 minutes ago created

Entering a toolbox container

To “enter” a container created with toolbox, we can use the enter subcommand. When we run the command an interactive shell is launched inside of it. If the command is launched without arguments, it tries to use the default container. Once again, since I am using Fedora, and I already built a container based on the host system, in order to use it I would just run:

$ toolbox enter

To enter a container built on one of the supported systems, we can, again, use the corresponding arguments for the --distro and --release options. To enter the container based on RHEL 9.1, for instance, we would run:

$ toolbox enter --distro rhel --release 9.1

Finally, to enter a container based on a custom image, or more generally reference a container by its name, all we need to do is to pass the name as the last argument. We already built a container based on the “ image” which is called “archlinux-toolbox-latest”. To enter it, we would run:

$ toolbox enter archlinux-toolbox-latest

If the command is successful, the shell PS1 prompt will change to reflect the fact that we are working inside the container:

⬢[doc@toolbox ~]$

Once inside a container we can install software just like we would do it on the target system. Since the container, as we already saw, shares a lot of things with the host system, we can also use it to install and run applications with a graphical interface, and launch them with the corresponding command. By using the run subcommand, we can also launch a command from a specific container directly, without using an interactive shell. Let’s see an example. For the sake of this tutorial I installed “Vorta” inside the “fedora-toolbox-38” container (Vorta is a graphical frontend for Borgbackup). In order to launch it without spawning an interactive shell, I would run:

$ toolbox run --container fedora-toolbox-38 vorta

Removing containers and images

Once we are done using a container we may want to remove it, perhaphs together with its base image. In order to do that we can use the rm and rmi commands, respectively. Sticking to previous examples, let’s suppose we want to remove the “archlinux-toolbox-latest” container. Here is the command we would run:

$ toolbox rm archlinux-toolbox-latest

The command will fail if the container we are trying to remove is still running. This may happen due to a know issue that makes containers not stopping after exiting. To be able to remove the container anyway we could either stop it directly with “podman”:

$ podman stop archlinux-toolbox-latest

Or use the --force option:

$ podman rm --force archlinux-toolbox-latest

To remove all the containers we created with toolbox at once, all we have to do is to use the --all option:

$ podman rm --force --all

To remove images instead of containers the procedure is the same as the options which can be used. The only thing that changes is the subcommand itself, which in this case is rmi. To remove the image on which the archlinux-toolbox-latest container is based on, we would run:

$ podman rmi


In this tutorial we learned how to use the Toolbx utility to create interactive container environments. Toolbx container are designed to integrate with the host system, sharing access to display manager, devices, network and users home directories; at the same time they can be used to install development tools and libraries, but also standard applications, in isolation.

Comments and Discussions
Linux Forum