DISTROBOX(1)

COMPATIBILITY
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.

  SUPPORTED CONTAINER MANAGERS
distrobox can run on either podman, docker or lilipod (https://github.com/89luca89/lilipod)

It depends either on podman configured in rootless mode or on docker configured without sudo (follow THESE instructions (https://docs.docker.com/engine/install/linux-postinstall/) )

•   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/

  CONTAINERS DISTROS
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 3.20 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:3.20 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
ALT Linux | p10 p11 sisyphus | docker.io/library/alt:p10 docker.io/library/alt:p11 docker.io/library/alt:sisyphus
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) | 11 12 13 testing unstable | quay.io/toolbx-images/debian-toolbox:11 quay.io/toolbx-images/debian-toolbox:12 quay.io/toolbx-images/debian-toolbox:13 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 40 41 42 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 quay.io/fedora/fedora-toolbox:41 quay.io/fedora/fedora-toolbox:42 quay.io/fedora/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
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 24.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:24.04 quay.io/toolbx/ubuntu-toolbox:latest
Chainguard Wolfi (Toolbox) |  | quay.io/toolbx-images/wolfi-toolbox:latest
Ublue | bluefin-cli ubuntu-toolbox fedora-toolbox wolfi-toolbox archlinux-distrobox powershell-toolbox | ghcr.io/ublue-os/bluefin-cli ghcr.io/ublue-os/bluefin-cli ghcr.io/ublue-os/ubuntu-toolbox ghcr.io/ublue-os/fedora-toolbox ghcr.io/ublue-os/wolfi-toolbox ghcr.io/ublue-os/arch-toolbox ghcr.io/ublue-os/powershell-toolbox
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 3.20 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:3.20 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 10 | quay.io/centos/centos:stream8 quay.io/centos/centos:stream9 quay.io/centos/centos:stream10
Chainguard Wolfi |  | cgr.dev/chainguard/wolfi-base:latest
Chimera Linux |  | docker.io/chimeralinux/chimera:latest
Crystal Linux |  | registry.gitlab.com/crystal-linux/misc/docker:latest
Debian | 7 8 9 10 11 12 13 | docker.io/debian/eol:wheezy docker.io/debian/eol:buster docker.io/debian/eol:bullseye 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 docker.io/linuxdeepin/deepin:beige
Fedora | 36 37 38 39 40 41 42 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:40 quay.io/fedora/fedora:41 quay.io/fedora/fedora:42 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 | nd120 | docker.io/library/neurodebian:nd120
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 registry.opensuse.org/opensuse/distrobox-bpftrace: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
Slackware |  | docker.io/vbatts/slackware:current
SteamOS |  | ghcr.io/linuxserver/steamos:latest
Ubuntu | 14.04 16.04 18.04 20.04 22.04 24.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:24.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 (https://github.com/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 (https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html) or nix portable (https://github.com/DavHau/nix-portable)

  NEW DISTRO SUPPORT
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!

  OLDER DISTRIBUTIONS
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.

  GPU ACCELERATION SUPPORT
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.