This project does not need a dedicated image. It can use any OCI images from docker-hub, quay.io, or any registry of your choice.
Many cloud images are stripped down on purpose to save size and may not include
commands such as which, mount, less or vi). Additional packages can be
installed once inside the container. We recommend using your preferred automation
tool inside the container if you find yourself having to repeatedly create new containers.
Maintaining your own custom image is also an option.
The main concern is having basic Linux utilities (mount), basic user management
utilities (usermod, passwd), and sudo correctly set.
distrobox can run on either podman, docker or lilipod
It depends either on podman configured in rootless mode
or on docker configured without sudo (follow THESE instructions)
- Minimum podman version: 2.1.0
- Minimum docker client version: 19.03.15
- Minimum lilipod version: v0.0.1
Follow the official installation guide here:
- https://podman.io/getting-started/installation
- https://docs.docker.com/engine/install
- https://docs.docker.com/engine/install/linux-postinstall/
Distrobox has been successfully tested on:
| Distro | Version | Notes |
|---|---|---|
| Alpine Linux | To setup rootless podman, look HERE | |
| Arch Linux | distrobox is available in the extra repository and distrobox-git is available in the AUR (thanks M0Rf30!). To setup rootless podman, look HERE |
|
| Bazzite | 38 | distrobox-git is preinstalled. |
| CentOS | 8 8 Stream 9 Stream |
distrobox is available in epel repos. (thanks alcir!) |
| ChromeOS | Debian 11 (docker with make-shared workaround #non-shared-mounts) Debian 12 (podman) |
using built-in Linux on ChromeOS mode which is debian-based, which can be upgraded from 11 bullseye to 12 bookworm (in fact 12 is recommended) |
| Debian | 11 12 Testing Unstable |
distrobox is available in default repos starting from version 12 (thanks michel-slm!!) |
| deepin | 23 Testing Unstable |
distrobox is available in default repos in testing and unstable |
| EndlessOS | 4.0.0 | |
| Fedora Silverblue/Kinoite | 35 36 37 Rawhide |
distrobox is available in default repos.(thanks alcir!) |
| Fedora | 35 36 37 38 Rawhide |
distrobox is available in default repos.(thanks alcir!) |
| Gentoo | To setup rootless podman, look HERE | |
| KDE neon | distrobox is available in default repo |
|
| Manjaro | To setup rootless podman, look HERE | |
| NixOS | 21.11 | Make sure to mind your executable paths. Sometimes a container will not have nix paths, and sometimes it will not have its own paths. Distrobox is available in Nixpkg collection (thanks AtilaSaraiva!)< To setup Docker, look HERE To setup Podman, look HERE and HERE |
| openSUSE | Leap 15.4 Leap 15.3 Leap 15.2 |
Packages are available here (thanks dfaggioli!). To install on openSUSE Leap 15, Use the following repository links in the zypper addrepo command: 15.4, 15.3, 15.2. Then: zypper refresh && zypper install distrobox. Podman under SUSE Leap, cannot initialize correctly the containers managed by distrobox until this openSUSE bug is fixed, or podman logging is configured properly. |
| openSUSE | Tumbleweed Aeon/Kalpa |
distrobox is available in default repos (thanks dfaggioli!) For Tumbleweed, do: zypper install distrobox. For Aeon/Kalpa, distrobox is installed by default. |
| SUSE Linux Enterprise Server | 15 Service Pack 4 15 Service Pack 3 15 Service Pack 2 |
Same procedure as the one for openSUSE (Leap, respective versions, of course). Use the following repository links in the zypper addrepo command: SLE-15-SP4, SLE-15-SP3, SLE-15-SP4. Then: zypper refresh && zypper install distrobox. Podman under SUSE Leap, cannot initialize correctly the containers managed by distrobox until this openSUSE bug is fixed, or podman logging is configured properly. |
| SteamOS | You can follow the Install Podman in a static manner or Install Lilipod in a static manner guide, this will install it in your $HOME and it will survive updates. | |
| RedHat | 8 9 |
distrobox is available in epel repos. (thanks alcir!) |
| Ubuntu | 18.04 20.04 22.04 22.10 23.04 |
Older versions based on 20.04 or earlier may need external repos to install newer Podman and Docker releases. Derivatives like Pop_OS!, Mint and Elementary OS should work the same. Now PPA available!, also distrobox is available in default repos from 22.10 onward (thanks michel-slm!) |
| Vanilla OS | 22.10 Orchid |
distrobox should be installed in the home directory using the official script |
| Void Linux | glibc musl |
|
| Windows | Oracle Linux 9 | using built-in Windows Subsystem for Linux |
Note also that in some distributions, root filesystem is not mounted as a shared mount, this will give an error like:
$ distrobox-enter
Error response from daemon: path /sys is mounted on /sys but it is not a shared or slave mount
Error: failed to start containers: ...To resolve this, use this command:
mount --make-rshared /To make it permanent, you can place it in /etc/rc.local.
If your distro of choice is not on the list, open an issue requesting support for it, we can work together to check if it is possible to add support for it.
Or just try using it anyway, if it works, open an issue and it will be added to the list!
Distrobox guests tested successfully with the following container images:
| Distro | Version | Images |
|---|---|---|
| AlmaLinux (Toolbox) | 8 9 |
quay.io/toolbx-images/almalinux-toolbox:8 quay.io/toolbx-images/almalinux-toolbox:9 quay.io/toolbx-images/almalinux-toolbox:latest |
| Alpine (Toolbox) | 3.16 3.17 3.18 3.19 edge |
quay.io/toolbx-images/alpine-toolbox:3.16 quay.io/toolbx-images/alpine-toolbox:3.17 quay.io/toolbx-images/alpine-toolbox:3.18 quay.io/toolbx-images/alpine-toolbox:3.19 quay.io/toolbx-images/alpine-toolbox:edge quay.io/toolbx-images/alpine-toolbox:latest |
| AmazonLinux (Toolbox) | 2 2022 |
quay.io/toolbx-images/amazonlinux-toolbox:2 quay.io/toolbx-images/amazonlinux-toolbox:2023 quay.io/toolbx-images/amazonlinux-toolbox:latest |
| Archlinux (Toolbox) | quay.io/toolbx/arch-toolbox:latest | |
| Bazzite Arch | ghcr.io/ublue-os/bazzite-arch:latest ghcr.io/ublue-os/bazzite-arch-gnome:latest |
|
| Centos (Toolbox) | stream8 stream9 |
quay.io/toolbx-images/centos-toolbox:stream8 quay.io/toolbx-images/centos-toolbox:stream9 quay.io/toolbx-images/centos-toolbox:latest |
| Debian (Toolbox) | 10 11 12 testing unstable |
quay.io/toolbx-images/debian-toolbox:10 quay.io/toolbx-images/debian-toolbox:11 quay.io/toolbx-images/debian-toolbox:12 quay.io/toolbx-images/debian-toolbox:testing quay.io/toolbx-images/debian-toolbox:unstable quay.io/toolbx-images/debian-toolbox:latest |
| Fedora (Toolbox) | 37 38 39 Rawhide |
registry.fedoraproject.org/fedora-toolbox:37 registry.fedoraproject.org/fedora-toolbox:38 registry.fedoraproject.org/fedora-toolbox:39 registry.fedoraproject.org/fedora-toolbox:40 registry.fedoraproject.org/fedora-toolbox:rawhide |
| openSUSE (Toolbox) | registry.opensuse.org/opensuse/distrobox:latest | |
| RedHat (Toolbox) | 8 9 |
registry.access.redhat.com/ubi8/toolbox registry.access.redhat.com/ubi9/toolbox quay.io/toolbx-images/rhel-toolbox:latest |
| Rocky Linux (Toolbox) | 8 9 |
quay.io/toolbx-images/rockylinux-toolbox:8 quay.io/toolbx-images/rockylinux-toolbox:9 quay.io/toolbx-images/rockylinux-toolbox:latest |
| Ubuntu (Toolbox) | 16.04 18.04 20.04 22.04 |
quay.io/toolbx/ubuntu-toolbox:16.04 quay.io/toolbx/ubuntu-toolbox:18.04 quay.io/toolbx/ubuntu-toolbox:20.04 quay.io/toolbx/ubuntu-toolbox:22.04 quay.io/toolbx/ubuntu-toolbox:latest |
| Ublue | bluefin-cli | ghcr.io/ublue-os/bluefin-cli |
| AlmaLinux | 8 8-minimal 9 9-minimal |
docker.io/library/almalinux:8 docker.io/library/almalinux:9 |
| Alpine Linux | 3.15 3.16 3.17 3.18 3.19 edge |
docker.io/library/alpine:3.15 docker.io/library/alpine:3.16 docker.io/library/alpine:3.17 docker.io/library/alpine:3.18 docker.io/library/alpine:3.19 docker.io/library/alpine:edge docker.io/library/alpine:latest |
| AmazonLinux | 1 2 2023 |
public.ecr.aws/amazonlinux/amazonlinux:1 public.ecr.aws/amazonlinux/amazonlinux:2 public.ecr.aws/amazonlinux/amazonlinux:2023 |
| Archlinux | docker.io/library/archlinux:latest | |
| Blackarch | docker.io/blackarchlinux/blackarch:latest | |
| CentOS Stream | 8 9 |
quay.io/centos/centos:stream8 quay.io/centos/centos:stream9 |
| CentOS | 7 | quay.io/centos/centos:7 |
| Chainguard Wolfi | cgr.dev/chainguard/wolfi-base:latest | |
| ClearLinux | docker.io/library/clearlinux:latest docker.io/library/clearlinux:base |
|
| Crystal Linux | registry.gitlab.com/crystal-linux/misc/docker:latest | |
| Debian | 7 8 9 10 11 12 |
docker.io/debian/eol:wheezy docker.io/library/debian:buster docker.io/library/debian:bullseye-backports docker.io/library/debian:bookworm-backports docker.io/library/debian:stable-backports |
| Debian | Testing | docker.io/library/debian:testing docker.io/library/debian:testing-backports |
| Debian | Unstable | docker.io/library/debian:unstable |
| deepin | 20 (apricot) 23 (beige) |
docker.io/linuxdeepin/apricot |
| Fedora | 36 37 38 39 Rawhide |
quay.io/fedora/fedora:36 quay.io/fedora/fedora:37 quay.io/fedora/fedora:38 quay.io/fedora/fedora:39 quay.io/fedora/fedora:rawhide |
| Gentoo Linux | rolling | docker.io/gentoo/stage3:latest |
| KDE neon | Latest | invent-registry.kde.org/neon/docker-images/plasma:latest |
| Kali Linux | rolling | docker.io/kalilinux/kali-rolling:latest |
| Mint | 21.1 | docker.io/linuxmintd/mint21.1-amd64 |
| Neurodebian | nd100 | docker.io/library/neurodebian:nd100 |
| openSUSE | Leap | registry.opensuse.org/opensuse/leap:latest |
| openSUSE | Tumbleweed | registry.opensuse.org/opensuse/distrobox:latest registry.opensuse.org/opensuse/tumbleweed:latest registry.opensuse.org/opensuse/toolbox:latest |
| Oracle Linux | 7 7-slim 8 8-slim 9 9-slim |
container-registry.oracle.com/os/oraclelinux:7 container-registry.oracle.com/os/oraclelinux:7-slim container-registry.oracle.com/os/oraclelinux:8 container-registry.oracle.com/os/oraclelinux:8-slim container-registry.oracle.com/os/oraclelinux:9 container-registry.oracle.com/os/oraclelinux:9-slim |
| RedHat (UBI) | 7 8 9 |
registry.access.redhat.com/ubi7/ubi registry.access.redhat.com/ubi8/ubi registry.access.redhat.com/ubi8/ubi-init registry.access.redhat.com/ubi8/ubi-minimal registry.access.redhat.com/ubi9/ubi registry.access.redhat.com/ubi9/ubi-init registry.access.redhat.com/ubi9/ubi-minimal |
| Rocky Linux | 8 8-minimal 9 |
quay.io/rockylinux/rockylinux:8 quay.io/rockylinux/rockylinux:8-minimal quay.io/rockylinux/rockylinux:9 quay.io/rockylinux/rockylinux:latest |
| Scientific Linux | 7 | docker.io/library/sl:7 |
| Slackware | docker.io/vbatts/slackware:current | |
| SteamOS | ghcr.io/linuxserver/steamos:latest | |
| Ubuntu | 14.04 16.04 18.04 20.04 22.04 23.04 |
docker.io/library/ubuntu:14.04 docker.io/library/ubuntu:16.04 docker.io/library/ubuntu:18.04 docker.io/library/ubuntu:20.04 docker.io/library/ubuntu:22.04 docker.io/library/ubuntu:23.04 |
| Vanilla OS | VSO | ghcr.io/vanilla-os/vso:main |
| Void Linux | glibc musl |
ghcr.io/void-linux/void-glibc-full:latest ghcr.io/void-linux/void-musl-full:latest |
Images marked with Toolbox are tailored images made by the community efforts in toolbx-images/images,
so they are more indicated for desktop use, and first setup will take less time.
Note however that if you use a non-toolbox preconfigured image,
the first distrobox-enter you'll perform
can take a while as it will download and install the missing dependencies.
A small time tax to pay for the ability to use any type of image. This will not occur after the first time, subsequent enters will be much faster.
NixOS is not a supported container distro, and there are currently no plans to bring support to it. If you are looking for unprivileged NixOS environments, we suggest you look into nix-shell or nix portable
If your distro of choice is not on the list, open an issue requesting support for it, we can work together to check if it is possible to add support for it.
Or just try using it anyway, if it works, open an issue and it will be added to the list!
For older distributions like CentOS 5, CentOS 6, Debian 6, Ubuntu 12.04, compatibility is not assured.
Their libc version is incompatible with kernel releases after >=4.11.
A work around this is to use the vsyscall=emulate flag in the bootloader of the
host.
Keep also in mind that mirrors could be down for such old releases, so you will need to build a custom distrobox image to ensure basic dependencies are met.
For Intel and AMD Gpus, the support is baked in, as the containers will install their latest available mesa/dri drivers.
For NVidia, you can use the --nvidia flag during create, see distrobox-create
documentation to discover how to use it.
Alternatively, you can use the nvidia-container-toolkit utility to set up the integration independently from the distrobox's own flag.