'\" t
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX" "1" "Mar 2024" "Distrobox" "User Manual"
.hy
.SH COMPATIBILITY
.PP
This project \f[B]does not need a dedicated image\f[R].
It can use any OCI images from docker-hub, quay.io, or any registry of
your choice.
.PP
Many cloud images are stripped down on purpose to save size and may not
include commands such as \f[V]which\f[R], \f[V]mount\f[R],
\f[V]less\f[R] or \f[V]vi\f[R]).
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.
.PP
The main concern is having basic Linux utilities (\f[V]mount\f[R]),
basic user management utilities (\f[V]usermod, passwd\f[R]), and
\f[V]sudo\f[R] correctly set.
.SS SUPPORTED CONTAINER MANAGERS
.PP
\f[V]distrobox\f[R] can run on either \f[V]podman\f[R], \f[V]docker\f[R]
or \f[V]lilipod\f[R] (https://github.com/89luca89/lilipod)
.PP
It depends either on \f[V]podman\f[R] configured in
\f[V]rootless mode\f[R] or on \f[V]docker\f[R] configured without sudo
(follow THESE
instructions (https://docs.docker.com/engine/install/linux-postinstall/))
.IP \[bu] 2
Minimum podman version: \f[B]2.1.0\f[R]
.IP \[bu] 2
Minimum docker client version: \f[B]19.03.15\f[R]
.IP \[bu] 2
Minimum lilipod version: \f[B]v0.0.1\f[R]
.PP
Follow the official installation guide here:
.IP \[bu] 2
<https://podman.io/getting-started/installation>
.IP \[bu] 2
<https://docs.docker.com/engine/install>
.IP \[bu] 2
<https://docs.docker.com/engine/install/linux-postinstall/>
.SS CONTAINERS DISTROS
.PP
Distrobox guests tested successfully with the following container
images:
.PP
.TS
tab(@);
lw(23.3n) lw(23.3n) lw(23.3n).
T{
Distro
T}@T{
Version
T}@T{
Images
T}
_
T{
AlmaLinux (Toolbox)
T}@T{
8 9
T}@T{
quay.io/toolbx-images/almalinux-toolbox:8
quay.io/toolbx-images/almalinux-toolbox:9
quay.io/toolbx-images/almalinux-toolbox:latest
T}
T{
Alpine (Toolbox)
T}@T{
3.16 3.17 3.18 edge
T}@T{
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:edge
quay.io/toolbx-images/alpine-toolbox:latest
T}
T{
AmazonLinux (Toolbox)
T}@T{
2 2022
T}@T{
quay.io/toolbx-images/amazonlinux-toolbox:2
quay.io/toolbx-images/amazonlinux-toolbox:2023
quay.io/toolbx-images/amazonlinux-toolbox:latest
T}
T{
Archlinux (Toolbox)
T}@T{
T}@T{
quay.io/toolbx/arch-toolbox:latest
T}
T{
Bazzite Arch
T}@T{
T}@T{
ghcr.io/ublue-os/bazzite-arch:latest
ghcr.io/ublue-os/bazzite-arch-gnome:latest
T}
T{
Centos (Toolbox)
T}@T{
stream8 stream9
T}@T{
quay.io/toolbx-images/centos-toolbox:stream8
quay.io/toolbx-images/centos-toolbox:stream9
quay.io/toolbx-images/centos-toolbox:latest
T}
T{
Debian (Toolbox)
T}@T{
10 11 12 testing unstable
T}@T{
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
T}
T{
Fedora (Toolbox)
T}@T{
37 38 39 Rawhide
T}@T{
registry.fedoraproject.org/fedora-toolbox:37
registry.fedoraproject.org/fedora-toolbox:38
registry.fedoraproject.org/fedora-toolbox:39
registry.fedoraproject.org/fedora-toolbox:rawhide
T}
T{
openSUSE (Toolbox)
T}@T{
T}@T{
registry.opensuse.org/opensuse/distrobox:latest
T}
T{
RedHat (Toolbox)
T}@T{
8 9
T}@T{
registry.access.redhat.com/ubi8/toolbox
registry.access.redhat.com/ubi9/toolbox
quay.io/toolbx-images/rhel-toolbox:latest
T}
T{
Rocky Linux (Toolbox)
T}@T{
8 9
T}@T{
quay.io/toolbx-images/rockylinux-toolbox:8
quay.io/toolbx-images/rockylinux-toolbox:9
quay.io/toolbx-images/rockylinux-toolbox:latest
T}
T{
Ubuntu (Toolbox)
T}@T{
16.04 18.04 20.04 22.04
T}@T{
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
T}
T{
T}@T{
T}@T{
T}
T{
AlmaLinux
T}@T{
8 8-minimal 9 9-minimal
T}@T{
docker.io/library/almalinux:8 docker.io/library/almalinux:9
T}
T{
Alpine Linux
T}@T{
3.15 3.16
T}@T{
docker.io/library/alpine:3.15 docker.io/library/alpine:3.16
docker.io/library/alpine:latest
T}
T{
AmazonLinux
T}@T{
1 2 2023
T}@T{
public.ecr.aws/amazonlinux/amazonlinux:1
public.ecr.aws/amazonlinux/amazonlinux:2
public.ecr.aws/amazonlinux/amazonlinux:2023
T}
T{
Archlinux
T}@T{
T}@T{
docker.io/library/archlinux:latest
T}
T{
CentOS Stream
T}@T{
8 9
T}@T{
quay.io/centos/centos:stream8 quay.io/centos/centos:stream9
T}
T{
CentOS
T}@T{
7
T}@T{
quay.io/centos/centos:7
T}
T{
Chainguard Wolfi
T}@T{
Small note: sudo is missing, use su-exec instead.
T}@T{
cgr.dev/chainguard/wolfi-base:latest
T}
T{
ClearLinux
T}@T{
T}@T{
docker.io/library/clearlinux:latest docker.io/library/clearlinux:base
T}
T{
Crystal Linux
T}@T{
T}@T{
registry.getcryst.al/crystal/misc/docker:latest
T}
T{
Debian
T}@T{
7 8 9 10 11 12
T}@T{
docker.io/debian/eol:wheezy docker.io/library/debian:buster-backports
docker.io/library/debian:bullseye-backports
docker.io/library/debian:bookworm-backports
docker.io/library/debian:stable-backports
T}
T{
Debian
T}@T{
Testing
T}@T{
docker.io/library/debian:testing
docker.io/library/debian:testing-backports
T}
T{
Debian
T}@T{
Unstable
T}@T{
docker.io/library/debian:unstable
T}
T{
deepin
T}@T{
20 (apricot) 23 (beige)
T}@T{
docker.io/linuxdeepin/apricot
T}
T{
Fedora
T}@T{
36 37 38 39 Rawhide
T}@T{
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
T}
T{
Gentoo Linux
T}@T{
rolling
T}@T{
docker.io/gentoo/stage3:latest
T}
T{
KDE neon
T}@T{
Latest
T}@T{
invent-registry.kde.org/neon/docker-images/plasma:latest
T}
T{
Kali Linux
T}@T{
rolling
T}@T{
docker.io/kalilinux/kali-rolling:latest
T}
T{
Mint
T}@T{
21.1
T}@T{
docker.io/linuxmintd/mint21.1-amd64
T}
T{
Neurodebian
T}@T{
nd100
T}@T{
docker.io/library/neurodebian:nd100
T}
T{
openSUSE
T}@T{
Leap
T}@T{
registry.opensuse.org/opensuse/leap:latest
T}
T{
openSUSE
T}@T{
Tumbleweed
T}@T{
registry.opensuse.org/opensuse/distrobox:latest
registry.opensuse.org/opensuse/tumbleweed:latest
registry.opensuse.org/opensuse/toolbox:latest
T}
T{
Oracle Linux
T}@T{
7 7-slim 8 8-slim 9 9-slim
T}@T{
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
T}
T{
RedHat (UBI)
T}@T{
7 8 9
T}@T{
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
T}
T{
Rocky Linux
T}@T{
8 8-minimal 9
T}@T{
quay.io/rockylinux/rockylinux:8 quay.io/rockylinux/rockylinux:8-minimal
quay.io/rockylinux/rockylinux:9 quay.io/rockylinux/rockylinux:latest
T}
T{
Scientific Linux
T}@T{
7
T}@T{
docker.io/library/sl:7
T}
T{
SteamOS
T}@T{
T}@T{
ghcr.io/linuxserver/steamos:latest
T}
T{
Ubuntu
T}@T{
14.04 16.04 18.04 20.04 22.04 23.04
T}@T{
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
T}
T{
Vanilla OS
T}@T{
VSO
T}@T{
ghcr.io/vanilla-os/vso:main
T}
T{
Void Linux
T}@T{
T}@T{
ghcr.io/void-linux/void-glibc-full:latest
T}
.TE
.PP
Images marked with \f[B]Toolbox\f[R] 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
\f[B]first\f[R] \f[V]distrobox-enter\f[R] you\[cq]ll perform can take a
while as it will download and install the missing dependencies.
.PP
A small time tax to pay for the ability to use any type of image.
This will \f[B]not\f[R] occur after the first time, \f[B]subsequent
enters will be much faster.\f[R]
.PP
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)
.SS NEW DISTRO SUPPORT
.PP
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.
.PP
Or just try using it anyway, if it works, open an issue and it will be
added to the list!
.SS OLDER DISTRIBUTIONS
.PP
For older distributions like CentOS 5, CentOS 6, Debian 6, Ubuntu 12.04,
compatibility is not assured.
.PP
Their \f[V]libc\f[R] version is incompatible with kernel releases after
\f[V]>=4.11\f[R].
A work around this is to use the \f[V]vsyscall=emulate\f[R] flag in the
bootloader of the host.
.PP
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.
.SS GPU ACCELERATION SUPPORT
.PP
For Intel and AMD Gpus, the support is baked in, as the containers will
install their latest available mesa/dri drivers.
.PP
For NVidia, you can use the \f[V]--nvidia\f[R] flag during create, see
distrobox-create documentation to discover how to use it.
.PP
Alternatively, you can use the nvidia-container-toolkit utility to set
up the integration independently from the distrobox\[cq]s own flag.