DISTROBOX(1)

💖 DISTROBOX(1) 💖 — the User Manual, group-chat edition 🫶

okay bestie, this is DISTROBOX and I am literally about to make you understand it. grab a snack. 🍓

---

🦋 COMPATIBILITY

okay so first thing, the iconic part: this project does not need a dedicated image. not one. it can use any OCI image from docker-hub, quay.io, or literally any registry of your choice. slay. ✨

ngl though, a lot of cloud images are stripped down on purpose to save size, and they might not even include commands such as which, mount, less or vi. the audacity 😭. no worries tho — you can install additional packages once you're inside the container. and if you find yourself repeatedly creating new containers (been there), we recommend using your preferred automation tool inside the container. maintaining your own custom image is also an option, if that's your main character era. 👑

the main concern? having these correctly set:

• basic Linux utilities (mount)
• basic user management utilities (usermod, passwd)
• and sudo correctly set

fr fr, if those three aren't vibing, nothing else will. 💀

---

💅 SUPPORTED CONTAINER MANAGERS

distrobox can run on either podman, docker or lilipod. pick your fighter. 🥊

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, bestie, do not freestyle this part:

• 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 👇 this is the roster, and yes it ate. 🔥

• AlmaLinux (Toolbox) — versions 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) — versions 3.20 3.21 3.22 edge
  • quay.io/toolbx-images/alpine-toolbox:3.20
  • quay.io/toolbx-images/alpine-toolbox:3.21
  • quay.io/toolbx-images/alpine-toolbox:3.22
  • quay.io/toolbx-images/alpine-toolbox:edge
  • quay.io/toolbx-images/alpine-toolbox:latest
• AmazonLinux (Toolbox) — versions 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 — versions 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) — versions stream9 stream10
  • quay.io/toolbx-images/centos-toolbox:stream9
  • quay.io/toolbx-images/centos-toolbox:stream10
  • quay.io/toolbx-images/centos-toolbox:latest
• Debian (Toolbox) — versions 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) — versions 38 39 40 41 42 43 Rawhide
  • 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:43
  • quay.io/fedora/fedora-toolbox:rawhide
• openSUSE (Toolbox)
  • registry.opensuse.org/opensuse/distrobox:latest
• RedHat (Toolbox) — versions 8 9
  • registry.access.redhat.com/ubi8/toolbox
  • registry.access.redhat.com/ubi9/toolbox
• Rocky Linux (Toolbox) — versions 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) — versions 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
  • ubuntu-toolbox → ghcr.io/ublue-os/ubuntu-toolbox
  • fedora-toolbox → ghcr.io/ublue-os/fedora-toolbox
  • wolfi-toolbox → ghcr.io/ublue-os/wolfi-toolbox
  • archlinux-distrobox → ghcr.io/ublue-os/arch-toolbox

---

and yeah, that's the whole compatibility vibe check for now. 💜

okay continuing the lineup, bestie — here's every single distro that's already been vetted, plus the exact images that go with each one 💖✨

• AlmaLinux — versions: 8, 8-minimal, 9 · images: docker.io/library/almalinux:8, docker.io/library/almalinux:9
• Alpine Linux — versions: 3.20, 3.21, 3.22, edge · images: docker.io/library/alpine:3.20, docker.io/library/alpine:3.21, docker.io/library/alpine:3.22, docker.io/library/alpine:edge, docker.io/library/alpine:latest
• AmazonLinux — versions: 1, 2, 2023 · images: public.ecr.aws/amazonlinux/amazonlinux:1, public.ecr.aws/amazonlinux/amazonlinux:2, public.ecr.aws/amazonlinux/amazonlinux:2023
• Archlinux — image: docker.io/library/archlinux:latest
• Blackarch — image: docker.io/blackarchlinux/blackarch:latest
• CentOS Stream — versions: 8, 9, 10 · images: quay.io/centos/centos:stream8, quay.io/centos/centos:stream9, quay.io/centos/centos:stream10
• Chainguard Wolfi — image: cgr.dev/chainguard/wolfi-base:latest
• Chimera Linux — image: docker.io/chimeralinux/chimera:latest
• Crystal Linux — image: registry.gitlab.com/crystal-linux/misc/docker:latest
• Debian — versions: 7, 8, 9, 10, 11, 12, 13 · images: 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) — images: docker.io/library/debian:testing, docker.io/library/debian:testing-backports
• Debian (Unstable) — image: docker.io/library/debian:unstable
• deepin — versions: 20 (apricot), 23 (beige) · images: docker.io/linuxdeepin/apricot, docker.io/linuxdeepin/deepin:beige
• Fedora — versions: 38, 39, 40, 41, 42, 43, Rawhide · images: 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:43, quay.io/fedora/fedora:rawhide
• Gentoo Linux — version: rolling · image: docker.io/gentoo/stage3:latest
• KDE neon — version: Latest · image: invent-registry.kde.org/neon/docker-images/plasma:latest
• Kali Linux — version: rolling · image: docker.io/kalilinux/kali-rolling:latest
• Mint — version: 22.3 · image: docker.io/linuxmintd/mint22.3-amd64
• Neurodebian — version: nd120 · image: docker.io/library/neurodebian:nd120
• openSUSE (Leap) — image: registry.opensuse.org/opensuse/leap:latest
• openSUSE (Tumbleweed) — images: 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 — versions: 8, 8-slim, 9, 9-slim, 10, 10-slim · images: 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, container-registry.oracle.com/os/oraclelinux:10, container-registry.oracle.com/os/oraclelinux:10-slim
• RedHat (UBI) — versions: 7, 8, 9 · images: 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 — versions: 8, 8-minimal, 9 · images: quay.io/rockylinux/rockylinux:8, quay.io/rockylinux/rockylinux:8-minimal, quay.io/rockylinux/rockylinux:9, quay.io/rockylinux/rockylinux:latest
• Slackware — image: docker.io/vbatts/slackware:current
• SteamOS — image: ghcr.io/linuxserver/steamos:latest
• Ubuntu — versions: 14.04, 16.04, 18.04, 20.04, 22.04, 24.04 · images: 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 — version: VSO · image: ghcr.io/vanilla-os/vso:main
• Void Linux — versions: glibc, musl · images: 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're way more geared toward desktop use, and your first setup is gonna be quicker. But heads up, bestie: if you go with a non-toolbox preconfigured image, that first distrobox-enter can take a minute — it's out here downloading and installing all the missing dependencies.

A small time tax to pay for the ability to use any type of image. 💅 And nope, it doesn't happen again after the first time — every enter after that is so much faster. ✨

Real talk: NixOS is not a supported container distro, and there are currently no plans to bring support to it. If you're looking for unprivileged NixOS environments, the suggestion is to look into nix-shell or nix portable.

🌈 NEW DISTRO SUPPORT 🌈

If your distro of choice isn't on the list, open an issue requesting support for it — you and the maintainers can work together to check if it's even possible to add support for it. 🤝

Or honestly? Just try using it anyway. If it works, open an issue and it'll get added to the list! That's the whole vibe. 👑

🌸 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 for 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'll need to build a custom distrobox image to make sure basic dependencies are met. 🛠️

💜 GPU ACCELERATION SUPPORT 💜

For Intel and AMD Gpus, the support is baked in, because the containers will install their latest available mesa/dri drivers. ✨

For NVidia, you can use the --nvidia flag during create — go peek at the 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 distrobox's own flag. 🫶

---

aaaand that's the whole page, bestie — you ate it. 💅 This one's brought to you by Distrobox, dated Mar 2026, and it lives in the manual as DISTROBOX(1). Go forth and containerize, you absolute icon. 🦋✨🎀