Sign up for the KDAB Newsletter
Stay on top of the latest news, publications, events and more.
Go to Sign-up


Find what you need - explore our website and developer resources
18 November 2026
If you haven't already, please check out the first part in this series. This article builds upon previous examples.
Although we don't have qutebrowseron the host, we can see that it did place configuration files in our $HOME directory:
~
🎄 ls .config | grep qutebrowser
qutebrowser
~
🎄 If we configure these files in the container and end up using qutebrowser in a different container, or on the host system, it will use this existing configuration.
This is nice for sharing things like .bashrc, .vimrc, and other personal configuration we want to avoid having to set up or copy every time we enter a new environment.
However, we may want configuration for specific containers, or to avoid mutating the home directory on the host. Luckily, we can control this behavior by specifying a host directory to act as the guest's $HOME.
$HOMELet's say I plan to use a program that will write dotfiles in my home directory, but I'd like to isolate it from my host environment. We can specify a custom home directory for a distrobox container when we create it with --home or -H to keep its $HOME separate from the host's $HOME.
Here's an example with a container of the glibc version of Void Linux:
~
🎄 mkdir voidhome
~
🎄 distrobox create -i ghcr.io/void-linux/void-glibc-full:latest -H /home/sus/voidhome -n void
Image ghcr.io/void-linux/void-glibc-full:latest not found.
Do you want to pull the image now? [Y/n]:
Trying to pull ghcr.io/void-linux/void-glibc-full:latest...
Getting image source signatures
Copying blob 05bf3236add7 done |
Copying blob f4b218fcab60 done |
Copying config 3b7f01fc80 done |
Writing manifest to image destination
3b7f01fc80c111dddbe830b2ea3bca4fa5d1f953ef69fe2c39d60f222f461a18
Creating 'void' using image ghcr.io/void-linux/void-glibc-full:latest [ OK ]
Distrobox 'void' successfully created.
To enter, run:
distrobox enter void
~ took 14s
🎄 distrobox enter void
Starting container... [ OK ]
Installing basic packages... [ OK ]
Setting up devpts mounts... [ OK ]
Setting up read-only mounts... [ OK ]
Setting up read-write mounts... [ OK ]
Setting up host's sockets integration... [ OK ]
Integrating host's themes, icons, fonts... [ OK ]
Setting up package manager exceptions... [ OK ]
Setting up distrobox profile... [ OK ]
Setting up sudo... [ OK ]
Setting up user groups... [ OK ]
Setting up kerberos integration... [ OK ]
Setting up user's group list... [ OK ]
Setting up existing user... [ OK ]
Setting up user home... [ OK ]
Ensuring user's access... [ OK ]
Setting up skel... [ OK ]
Container Setup Complete!
[sus@void sus]$ pwd
/home/sus
[sus@void sus]$ cd $HOME
[sus@void ~]$ pwd
/home/sus/voidhome
[sus@void ~]$ Now we installsurfwith Void Linux'sxbpspackage manager, and run it.
This will put a .surfdirectory in ~ (which is/home/sus/voidhome)
[sus@void ~]$ sudo xbps-install -S
...
...
[sus@void ~]$ sudo xbps-install surf
...
...
[sus@void ~]$ surf duckduckgo.com
...
...
^C
[sus@void ~]$ ls -a /home/sus | grep surf
[sus@void ~]$ ls -a /home/sus/voidhome | grep surf
.surf
[sus@void ~]$ Notice .surf appears in /home/sus/voidhome and not in /home/sus.
This can be very useful if working on lots of different projects that need to be isolated from one another, or just for trying out new software.
You can avoid filling your home directory with configuration files and keep it clean, so it's easier to look through when you need to find something. Then each container's home directory contains only the configuration files it needs. Overall, it keeps things tidier and easier to manage.
Now, let's say I want to use starship as my prompt inside Void. I want to just reuse what I already have on my host machine rather than reinstalling it in the container.
Let's return to our host system and re-create the container, sharing starship. We exit just like any other shell, by typing exit or hitting Ctrl+D.
[sus@void ~]$
logout
~ took 10m34s
🎄 First, let's take a look at the distrobox containers we have.
distrobox list or distrobox ls lists the state of all your distrobox containers. We can cross reference it here with the result of executing podman images, which may have additional containers that are NOT from distrobox (in this case they are the same):
~
🎄 distrobox ls
ID | NAME | STATUS | IMAGE
7afe72865b1c | stage3-latest | Up 6 hours | docker.io/gentoo/stage3:latest
0b1471845843 | void | Up 7 hours | ghcr.io/void-linux/void-glibc-full:latest
b24e66f42337 | alpine | Up About a minute | docker.io/library/alpine:latest
~
🎄 podman images
REPOSITORY TAG IMAGE ID CREATED SIZE
ghcr.io/void-linux/void-glibc-full latest 3b7f01fc80c1 2 days ago 149 MB
docker.io/library/alpine latest b0c9d60fc5e3 6 days ago 16.3 MB
docker.io/gentoo/stage3 latest aacab3c9b8ca 5 weeks ago 2.13 GB
~
🎄 As you can see, the void container is still running even though we exited the shell session (`Up 7 hours`). We want to stop it, remove it, and replace it with a new container. We can first execute distrobox stop to stop it, then execute distrobox rm to remove it.
~
🎄 distrobox stop void
Do you really want to stop void? [Y/n]:
WARN[0000] failed to kill all processes, possibly due to lack of cgroup (Hint: enable cgroup v2 delegation) error="cgroup not exist"
void
~
🎄 distrobox rm void
Do you really want to delete containers: void? [Y/n]:
Container void not running.
Do you want to start it to remove exported apps and binaries? [y/N]:
Removing container...
void
~ took 3s
🎄 Of course, any packages installed to that container are now lost, as the container is removed.
Now, let's find the path of starship and mount it into a new container. We'll make it read-only (`ro`):
~
🎄 which starship
/usr/local/bin/starship
~
🎄 distrobox create -i ghcr.io/void-linux/void-glibc-full:latest -H /home/sus/voidhome -n void --volume /usr/local/bin/starship:/usr/local/bin/starship:ro
Creating 'void' using image ghcr.io/void-linux/void-glibc-full:latest [ OK ]
Distrobox 'void' successfully created.
To enter, run:
distrobox enter void
~
🎄 distrobox enter void
Starting container... [ OK ]
Installing basic packages... [ OK ]
Setting up devpts mounts... [ OK ]
Setting up read-only mounts... [ OK ]
Setting up read-write mounts... [ OK ]
Setting up host's sockets integration... [ OK ]
Integrating host's themes, icons, fonts... [ OK ]
Setting up package manager exceptions... [ OK ]
Setting up distrobox profile... [ OK ]
Setting up sudo... [ OK ]
Setting up user groups... [ OK ]
Setting up kerberos integration... [ OK ]
Setting up user's group list... [ OK ]
Setting up existing user... [ OK ]
Setting up user home... [ OK ]
Ensuring user's access... [ OK ]
Setting up skel... [ OK ]
Container Setup Complete!
[sus@void sus]$ eval $(starship init bash)
/home/sus
⬢ [void] ❯ That works, it runs starship!
But it is not using my config file. Notice my host prompt usually has a 🎄 emoji in place of ❯.
My starship config file is in /home/sus/.config/starship.toml. This is mounted, and I can read from and write things into /home/sus still if I want. However, since $HOME is /home/sus/voidhome, starship looks there for a configuration file and cannot find one.
We can fix this by creating a symbolic link to the config file in /home/sus/voidhome/.config.
[sus@void ~]$ cd .config
[sus@void .config]$ ln -s ../../.config/starship.toml starship.toml
[sus@void .config]$ eval $(starship init bash)
~/.config
⬢ [void] 🎄 Now, since voidhome is its own home directory, it already has its own .bashrc. We can put the command eval $(starship init bash) in there to start it automatically. Or, if we please, we can copy our entire .bashrc from the host directory.
In addition to controlling volume mounting, we can also control what deices, groups, and namespaces are shared with further granularity:
--unshare-devsys: do not share host devices and sysfs dirs from host
--unshare-groups: do not forward user's additional groups into the container
--unshare-ipc: do not share ipc namespace with host
--unshare-netns: do not share the net namespace with host
--unshare-process: do not share process namespace with host
--unshare-all: activate all the unshare flags below Sometimes, you might want to use something from your host environment while in a terminal session in a guest container. For this, we use distrobox-host-exec.
Note: You need flatpak on host for this to work. It uses host-spawn which uses flatpak. Older versions of distrobox used to provide an error but at the time of writing it just does nothing if flatpak is not installed.
A simple example could be checking on the container itself by running podman on the host. Consider this command:
bash
distrobox-host-exec podman ps This can also be useful for running other containers on the host. If you are in a container meant to emulate a target environment, and you need to also spin up a database container, you can access the host to quickly use podman without leaving the active terminal session or spawning another tab or window.
Another example is when using a tool that doesn’t need to be dependent on the guest environment. For instance, using git on a guest running Fedora is generally not going to differ from using it on a host running Ubuntu, except for very specific cases involving versioning. Why install git on the guest if we already have it on the host?
distrobox-export takes care of exporting an application or binary from the container to the host.
The exported app will be easily available in your normal application launcher, and it will automatically be launched from the container it is exported from.
sus@alpine:~$ distrobox-export -a qutebrowser
Application qutebrowser successfully exported.
OK!
qutebrowser will appear in your applications list in a few seconds. I use xfce4-appfinder to search and launch .desktop files.
So, without leaving the alpine container, i can look for qutebrowser on my host like so:
sus@alpine:~$ distrobox-host-exec xfce4-appfinder xfce4-appfinder shows this entry:
qutebrowser (on alpine)
A keyboard-driven, vim-like browser based on Python and Qt
This makes it convenient to launch a program that only exists in a container without having to enter the container in a terminal.
Let's assume we need to use ROS (Robot Operating System) 2 for a project. The ROS2 package repositories for Ubuntu contain different, incompatible versions per Ubuntu version. So, specific versions of ROS2 are often installed in specific versions of Ubuntu. You may need Ubuntu 18.04 for the ROS2 distribution you are targeting in your project, but your base OS may be Ubuntu 24.04. Distrobox is an excellent solution to use Ubuntu 18.04 packages easily on an Ubuntu 24.04 system. Let's explore several versions of Ubuntu and ROS2 in Distrobox containers.
We'll start by creating a container for Ubuntu 16.04:
~
🎄 distrobox create -n ubuntu16 -i docker.io/library/ubuntu:16.04 -H /home/sus/ubuntu16home We can also do the same for Ubuntu 20.04 and 22.04.
In each of these containers, we set up the ros2 package repository as explained in the documentation.
sus@ubuntu16:~$ sudo apt install software-properties-common
sus@ubuntu16:~$ sudo add-apt-repository universe
sus@ubuntu16:~$ sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
sus@ubuntu16:~$ sudo apt update Now we get some results when searching for ros2cli with apt:
sus@ubuntu16:/home/sus$ apt search ros2cli
Sorting... Done
Full Text Search... Done
ros-ardent-ros2cli/xenial 0.4.1-0xenial-20180328-110901-0800 amd64
Framework for ROS 2 command line tools.
ros-r2b2-ros2cli/xenial 0.0.2-0xenial-20170705-121127-0800 amd64
Framework for ROS 2 command line tools.
ros-r2b3-ros2cli/xenial 0.0.3-0xenial-20170913-183245-0800 amd64
Framework for ROS 2 command line tools. Note that we have ROS 2 ardent, r2b2, and r2b3.
Now let's check what versions are available when we're on Ubuntu 20.04:
sus@ubuntu16:/home/sus$ logout
~ took 24s
🎄 distrobox enter ubuntu20
sus@ubuntu20:/home/sus$ apt search ros2cli
Sorting... Done
Full Text Search... Done
ros-foxy-ros2cli/focal 0.9.13-1focal.20230527.052009 amd64
Framework for ROS 2 command line tools.
ros-foxy-ros2cli-common-extensions/focal 0.1.1-1focal.20230527.064045 amd64
Meta package for ros2cli common extensions
ros-galactic-ros2cli/focal 0.13.5-1focal.20221207.074558 amd64
Framework for ROS 2 command line tools.
ros-galactic-ros2cli-common-extensions/focal 0.1.1-2focal.20221208.073244 amd64
Meta package for ros2cli common extensions
ros-galactic-ros2cli-test-interfaces/focal 0.13.5-1focal.20221203.094831 amd64
A package containing interface definitions for testing ros2cli.
ros-galactic-ros2cli-test-interfaces-dbgsym/focal 0.13.5-1focal.20221203.094831 amd64
debug symbols for ros-galactic-ros2cli-test-interfaces
ros-rolling-ros2cli/focal 0.17.1-1focal.20220126.184012 amd64
Framework for ROS 2 command line tools.
ros-rolling-ros2cli-common-extensions/focal 0.1.1-2focal.20220126.191606 amd64
Meta package for ros2cli common extensions
ros-rolling-ros2cli-test-interfaces/focal 0.17.1-1focal.20220126.184021 amd64
A package containing interface definitions for testing ros2cli.
ros-rolling-ros2cli-test-interfaces-dbgsym/focal 0.17.1-1focal.20220126.184021 amd64
debug symbols for ros-rolling-ros2cli-test-interfaces Now the ROS 2 distros available to us are foxy, galactic, and a rolling release version.
There are also now additional packages for common extensions and testing interfaces that were not available on Ubuntu 18.04.
Let's do the same again with Ubuntu 22.04:
sus@ubuntu20:/home/sus$ logout
~ took 11s
🎄 distrobox enter ubuntu22 -- apt search ros2cli
Sorting... Done
Full Text Search... Done
ros-humble-ros2cli/jammy 0.18.11-1jammy.20241128.015950 amd64
Framework for ROS 2 command line tools.
ros-humble-ros2cli-common-extensions/jammy 0.1.1-4jammy.20241128.035113 amd64
Meta package for ros2cli common extensions
ros-humble-ros2cli-test-interfaces/jammy 0.18.11-1jammy.20241128.004455 amd64
A package containing interface definitions for testing ros2cli.
ros-humble-ros2cli-test-interfaces-dbgsym/jammy 0.18.11-1jammy.20241128.004455 amd64
debug symbols for ros-humble-ros2cli-test-interfaces
ros-iron-ros2cli/jammy 0.25.8-1jammy.20241114.221836 amd64
Framework for ROS 2 command line tools.
ros-iron-ros2cli-common-extensions/jammy 0.2.2-3jammy.20241114.231220 amd64
Meta package for ros2cli common extensions
ros-iron-ros2cli-test-interfaces/jammy 0.25.8-1jammy.20241109.032345 amd64
A package containing interface definitions for testing ros2cli.
ros-iron-ros2cli-test-interfaces-dbgsym/jammy 0.25.8-1jammy.20241109.032345 amd64
debug symbols for ros-iron-ros2cli-test-interfaces
ros-rolling-ros2cli/jammy 0.31.1-1jammy.20240216.163718 amd64
Framework for ROS 2 command line tools.
ros-rolling-ros2cli-common-extensions/jammy 0.3.0-1jammy.20240216.184201 amd64
Meta package for ros2cli common extensions
ros-rolling-ros2cli-test-interfaces/jammy 0.31.1-1jammy.20240208.082438 amd64
A package containing interface definitions for testing ros2cli.
ros-rolling-ros2cli-test-interfaces-dbgsym/jammy 0.31.1-1jammy.20240208.082438 amd64
debug symbols for ros-rolling-ros2cli-test-interfaces Now we have humble, iron, and rolling.
Finally, my host machine is actually running Ubuntu 24.04, so let's see what we have there:
~
🎄 apt search ros2cli
Sorting... Done
Full Text Search... Done
ros-jazzy-ros2cli/noble 0.32.2-1noble.20241228.001812 amd64
Framework for ROS 2 command line tools.
ros-jazzy-ros2cli-common-extensions/noble 0.3.0-3noble.20241228.015311 amd64
Meta package for ros2cli common extensions
ros-jazzy-ros2cli-test-interfaces/noble 0.32.2-1noble.20241227.215302 amd64
A package containing interface definitions for testing ros2cli.
ros-jazzy-ros2cli-test-interfaces-dbgsym/noble 0.32.2-1noble.20241227.215302 amd64
debug symbols for ros-jazzy-ros2cli-test-interfaces
ros-rolling-ros2cli/noble,now 0.36.1-1noble.20241226.171830 amd64 [installed,automatic]
Framework for ROS 2 command line tools.
ros-rolling-ros2cli-common-extensions/noble,now 0.4.0-1noble.20241226.174333 amd64 [installed,automatic]
Meta package for ros2cli common extensions
ros-rolling-ros2cli-test-interfaces/noble 0.36.1-1noble.20241226.151410 amd64
A package containing interface definitions for testing ros2cli.
ros-rolling-ros2cli-test-interfaces-dbgsym/noble 0.36.1-1noble.20241226.151410 amd64
debug symbols for ros-rolling-ros2cli-test-interfaces There we get jazzy and rolling.
As ROS versions are not compatible with one another, if your project is targeting ROS galactic, using a different version will almost certainly cause compilation errors.
Assuming a target environment is Ubuntu 20.04 and ROS galactic, but your development machine is not, you can use distrobox to set this up and build against the correct ROS version on the correct OS environment. You can avoid spinning up a VM, which is a common way to approach such a problem, and additionally retain your home directory, any tools on the host machine, your x11 or wayland session, and easily test graphical applications written for the target platform.
Furthermore, imagine debugging a specific issue where packages provided by a distribution's package manager play a role in reproducing the bug. For instance, you may be using a specific ROS version that you have compiled from source instead of using distro packages; however, even though the ROS version is correct, it may also be causing problems by interacting with some other library that doesn’t match the version of the target environment. These kinds of issues are more easily addressable with distrobox.
In the next part of this series, we will cover some more advanced topics and use cases of the tool.