| DISTROBOX(1) | User Manual | DISTROBOX(1) |
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 or docker
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/))
Follow the official installation guide here:
Distrobox guests tested successfully with the following container images:
| Distro | Version | Images |
| AlmaLinux (UBI) | 8 | quay.io/almalinux/8-base:8 quay.io/almalinux/8-init:8 |
| AlmaLinux | 8 8-minimal 9 9-minimal | quay.io/almalinux/almalinux:8 quay.io/almalinux/almalinux:9 quay.io/almalinux/almalinux:9-minimal |
| Alpine Linux | 3.15 3.16 | docker.io/library/alpine:3.15 docker.io/library/alpine:3.16 docker.io/library/alpine:latest |
| AmazonLinux | 1 2 2022 | public.ecr.aws/amazonlinux/amazonlinux:1 public.ecr.aws/amazonlinux/amazonlinux:2 public.ecr.aws/amazonlinux/amazonlinux:2022.0.20220531.0 |
| Archlinux | docker.io/library/archlinux:latest | |
| CentOS Stream | 8 9 | quay.io/centos/centos:stream8 quay.io/centos/centos:stream9 |
| CentOS | 7 | quay.io/centos/centos:7 |
| ClearLinux | docker.io/library/clearlinux:latest docker.io/library/clearlinux:base | |
| Debian | 7 8 9 10 11 | docker.io/debian/eol:wheezy docker.io/debian/eol:jessie docker.io/library/debian:9 docker.io/library/debian:10 docker.io/library/debian:stable 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 |
| Fedora | 35 36 37 38 Rawhide | registry.fedoraproject.org/fedora-toolbox:37 quay.io/fedora/fedora:35 quay.io/fedora/fedora:36 registry.fedoraproject.org/fedora:37 quay.io/fedora/fedora:38 |
| Gentoo Linux | rolling | docker.io/gentoo/stage3:latest |
| Kali Linux | rolling | docker.io/kalilinux/kali-rolling:latest |
| Mageia | 8 | docker.io/library/mageia |
| Neurodebian | nd100 | docker.io/library/neurodebian:nd100 |
| Opensuse | Leap | registry.opensuse.org/opensuse/leap:latest |
| Opensuse | Tumbleweed | 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/ubi7/ubi-init 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 | 14.2 | docker.io/vbatts/slackware:14.2 |
| Ubuntu | 14.04 16.04 18.04 20.04 22.04 22.10 | 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 |
| Void Linux | ghcr.io/void-linux/void-linux:latest-full-x86_64 ghcr.io/void-linux/void-linux:latest-full-x86_64-musl |
Note however that if you use a non-toolbox preconfigured image (e.g. images pre-baked to work with <https://github.com/containers/toolbox>), 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 unprivlaged NixOS environments, we suggest you look into nix-shell (https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html).
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.
| Dec 2022 | Distrobox |