Backup and restore Toolboxes

Toolboxes started life often described as disposable containers – and that is still one of their major uses: install stuff, then try it out in the relative safety of a container, and lastly, cleanly dispose of it. Minimal risk, fuss and without pesky residual libraries and applications hanging around on the host long after you have finished.

So — why would you backup a Toolbox? Sometimes, they have more permanent uses, contain complex and lengthy installs, or are being used for critical applications. For example, Toolboxes can be used as a development environment, containing hardware associated drivers and applications. Or they could be used for an application you want to run in a container for which there is no Flatpak, or one that has requirements a Flatpak doesn’t satisfy. While they can be handy to use on Fedora Workstation, toolbox containers are often essential for Silverblue users since they offer an easy solution to installing applications that can’t successfully be installed by rpm-ostree. Or for applications that may not have a Flatpak version readily available. In the above situations a busted Toolbox can be a major headache. But if a backup exists, you can quickly restore a Toolbox or move it to another workstation.

The backup process uses Podman to create an image of an existing toolbox container, and save that image to an archive file. To restore the toolbox container, load the image from the archive file and then create a Toolbox from that image. The new toolbox container will be an identical copy of your backed up toolbox container.

It is important to note this process does not backup data, just what you have installed in the toolbox container. This includes packages installed from repositories or from a local rpm file using dnf. If you need to backup data, Podman’s commit command that will be used to capture an image of the toolbox container, has an option to include volumes attached to the container.

Creating a backup

To backup a toolbox container you will need it’s name and container ID which can be gotten by using toolbox list. For this example I am going to backup my golang development toolbox container, imaginatively named go.

$ toolbox list

00ff783a102f  go              5 weeks ago  exited

If the container’s status shows as running , you should stop it using podman container stop container_name. Although the commit command has a -p for pause option, make sure that the Toolbox is not running, which helps it initialize correctly when restored from backup.

$ podman container stop go

To create an image of the toolbox container use

podman container commit -p container_ID backup-image-name
Depending on the complexity of the Toolbox, this can take a little while.

 $ podman container commit -p 00ff783a102f  go-backup

Now to confirm the image has been created type…

$ toolbox list

You should get output similar to what is below…

cfcb13046db7 localhost/go-backup:latest About a minute ago

00ff783a102f go 5 weeks ago exited

Now to save the backup image to a tar archive file using podman save -o backup-filename.tar backup-image-name.

$ podman save -o go.tar go-backup

Confirm the archive file, our toolbox container backup, was created.

$ ls


Do some tidying up, remove the backup image and, if needed, remove the original Toolbox.

$ podman rmi go-backup

$ toolbox rm go

Restore a backup

To create an image from the backup file that was made above, you do it with the command podman load -i backup_filename.

$ podman load -i go.tar

Then you can confirm the image was created with…

$ toolbox list

IMAGE ID      IMAGE NAME                  CREATED
cfcb13046db7  localhost/go-backup:latest  17 minutes ago

Now create a toolbox container from the restored image, with toolbox create –container container_name ––image image_name, specifying the full repository and version tag as the image name.

$ toolbox create --container go --image localhost/go-backup:latest

Confirm that the toolbox was created.

$ toolbox list

IMAGE ID      IMAGE NAME                CREATED
cfcb13046db7 localhost/go-backup:latest 20 minutes ago

34cef6b7e28d go 21 seconds ago configured localhost/go-backup:latest

Finally, you can test that the restored Toolbox works…

$ toolbox enter --container go

If you can enter the newly created toolbox container, you will see the toolbox prompt and will have successfully backed up and restored your Pet toolbox container.

FAQs and Guides Fedora Contributor Community For Developers For System Administrators Using Software


  1. Jens Petersen

    Thanks for this useful article: it should be particularly useful for migrating or sharing toolbox images.

    What I have been doing personally for my general toolbox containers is having a small toolbox initial setup script which I run in a newly created toolbox to install all the common packages I need for development like Emacs, compilers, etc. (I created it initially by noting down whenever I installed some missing package(s) into toolbox.)

    I also have a small script (called sys-rpms) for recording all currently installed rpms in a system for completeness, though I find the above setup install script is really sufficient for me.

  2. Vernay Bruno

    Same here, using a basic script for common ground.
    I am also a bit surprised that backuping the image is still a thing in the “Infrastructure as code” world. I guess everyone has its workflow, but I like to save my toolbox script with the project in git and it seems easier than managing backups.

  3. Joe Fidler

    Completely agree that backing up a toolbox is a bit clumsy a lot of the time – it’s often much easier to create the toolbox from fresh, especially if you use a script to automate setup inside the toolbox. I have found the backup method useful when a install involves drivers that cannot be pulled from repositories, or you are replicating a toolbox to multiple local machines where copying an image to a USB drive can save multiple downloads.

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