A quick introduction to Toolbox on Fedora

Toolbox allows you to sort and manage your development environments in containers without requiring root privileges or manually attaching volumes. It creates a container where you can install your own CLI tools, without installing them on the base system itself. You can also utilize it when you do not have root access or cannot install programs directly. This article gives you an introduction to toolbox and what it does.

Installing Toolbox

Silverblue includes Toolbox by default. For the Workstation and Server editions, you can grab it from the default repositories using dnf install toolbox.

Creating Toolboxes

Open your terminal and run toolbox enter. The utility will automatically request permission to download the latest image, create your first container, and place your shell inside this container.

$ toolbox enter
No toolbox containers found. Create now? [y/N] y
Image required to create toolbox container.
Download registry.fedoraproject.org/f30/fedora-toolbox:30 (500MB)? [y/N]: y

Currently there is no difference between the toolbox and your base system. Your filesystems and packages appear unchanged. Here is an example using a repository that contains documentation source for a resume under a ~/src/resume folder. The resume is built using the pandoc tool.

$ pwd  
$ cd src/resume/ 
$ head -n 5 Makefile 
all: pdf html rtf text docx

pdf: init
 pandoc -s -o BUILDS/resume.pdf markdown/*

$ make pdf
bash: make: command not found
$ pandoc -v
bash: pandoc: command not found

This toolbox does not have the programs required to build the resume. You can remedy this by installing the tools with dnf. You will not be prompted for the root password, because you are running in a container.

$ sudo dnf groupinstall "Authoring and Publishing" -y && sudo dnf install pandoc make -y
$ make all #Successful builds
mkdir -p BUILDS
pandoc -s -o BUILDS/resume.pdf markdown/*
pandoc -s -o BUILDS/resume.html markdown/*
pandoc -s -o BUILDS/resume.rtf markdown/*
pandoc -s -o BUILDS/resume.txt markdown/*
pandoc -s -o BUILDS/resume.docx markdown/*
$ ls BUILDS/
resume.docx  resume.html  resume.pdf  resume.rtf  resume.txt

Run exit at any time to exit the toolbox.

$ cd BUILDS/
$ pandoc --version || ls
pandoc 2.2.1
Compiled with pandoc-types, texmath, skylighting 0.7.5
for a particular purpose.
resume.docx  resume.html  resume.pdf  resume.rtf  resume.txt
$ exit 
$ pandoc --version || ls
bash: pandoc: command not found...
resume.docx  resume.html  resume.pdf  resume.rtf  resume.txt

You retain the files created by your toolbox in your home directory. None of the programs installed in your toolbox will be available outside of it.

Tips and tricks

This introduction to toolbox only scratches the surface. Here are some additional tips, but you can also check out the official documentation.

  • Toolbox –help will show you the man page for Toolbox
  • You can have multiple toolboxes at once. Use toolbox create -c Toolboxname and toolbox enter -c Toolboxname
  • Toolbox uses Podman to do the heavy lifting. Use toolbox list to find the IDs of the containers Toolbox creates. Podman can use these IDs to perform actions such as rm and stop. (You can also read more about Podman in this Magazine article.)

Photo courtesy of Florian Richter from Flickr.

For Developers For System Administrators Using Software


  1. Martin Ueding

    That’s a bad Makefile, it will always re-build everything because the targets are not the files that are generated.

  2. Maciej

    Toolbox is the tool that I thought docker is when I didn’t knew anything about docker. 🙂

    • Interesting that you say that. I’ve never thought of docker in that way, but I can completely see where you are coming from. Especialy if you don’t have the filesystem sandbox concepts of docker understood yet.

    • Interesting that you say that, I can definitely see what you are talking about, especially if you do not have the filesystem sandboxing fully understood.

      • Maciej

        My thinking was Docker = Containers = Much better “chroot”
        When I installed docker for the first time I was thinking that I’m installing some sort of tool for isolating stuff easily. Than came confusion about the difference between image and container, and OMG where are my all changes after container stopped, and what do you mean I should run only one service in one container? Maybe I still have physical server and I want to run couple of services in one place and just move one big blob around? Moreover why you (docker) insist so much on running this stuff that other people made? Why I can’t just point you too my own rootfs and run that? It was painful and I don’t think I like docker that much. Yes I know it’s for running stuff in the clouds, but still…

        • Gr

          The same view of all that Dockers!

          Still confused of using Docker and cant move of virtual machine, old-school nice little virtual machines.

          Do anybody have a raw howto to explain why “docker vs vms” is winnig?

          • Maciej

            I really don’t like compering these technologies. Containers are only able to isolate and run many different “userlands”, so no different kernels and no different OSs. You can use docker and you will probably not even know that there is still some VM underneath.

  3. Guus Bonnema

    I do have a question: how does toolbox and the files I can maintain using toolbox relate to backup programs? I.e. If I want to backup my files and I have say 5 toolbox instances, how does that work? Could you add that to the article?

    • For the files (Such as the ones under /home/rwaltr/src/resume In the above example. ) you can use any tool that can handle file level replication such as Rsync, SCP, Restic, etc. Toolbox does not separate your home directory from your base system, So any backups you are running on the base system would also pick up on any changes that were performed in Toolbox.

      The Toolbox containers themselves are actually ran by Podman, You can find where your podman containers are stored with “grep graphroot $HOME/.config/containers/storage.conf ” I suppose you could run the backups directly in the container, But I am unsure of the use case for that.

  4. Alex

    There just seem layer after layer coming up in the containers space, hard to track what’s going on, and how everything works… I pretty much use Singularity (https://sylabs.io/docs/) for purposes explained in this article, but that’s because it came first, and has an excellent support for parallel execution on clusters and supercomputers. Would love to see more detailed comparison between various container solutions for developers.

  5. Danie

    How do I make new instances of non-default images?

    I thought it would be:
    toolbox create –release=32

  6. Ed Nicholson

    Do Toolbox containers run on Docker in Windows10
    I hate to ask, but work…

    • I am unable to test, But I wouldn’t see why not, need to check that the right volumes are being passed though,

Comments are Closed

The opinions expressed on this website are those of each author, not of the author's employer or of Red Hat. Fedora Magazine aspires to publish all content under a Creative Commons license but may not be able to do so in all cases. You are responsible for ensuring that you have the necessary permission to reuse any work on this site. The Fedora logo is a trademark of Red Hat, Inc. Terms and Conditions