Skip to content

Latest commit

 

History

History
231 lines (176 loc) · 16.5 KB

compatibility.md

File metadata and controls

231 lines (176 loc) · 16.5 KB

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 or docker

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

Follow the official installation guide here:

Host Distros

Distrobox has been successfully tested on:

Distro Version Notes
Alpine Linux 3.14
3.15
To setup rootless podman, look HERE
Arch Linux distrobox and distrobox-git are available in AUR (thanks M0Rf30!).
To setup rootless podman, look HERE
CentOS 8
8 Stream
9 Stream
distrobox is available in epel repos. (thanks alcir!)
Debian 11
Testing
Unstable
distrobox is available in default repos in testing and unstable (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
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
MicroOS
distrobox is available in default repos (thanks dfaggioli!)
For Tumbleweed, do: zypper install distrobox.
For MicroOS, do: transactional-update pkg install distrobox and reboot the system.
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 3 You can use steamos-readonly disable and follow Arch Linux instructions. This will NOT survive updates.
Alternatively you can follow the Install Podman 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!)
Void Linux glibc Systemd service export will not work.

Install Podman in a static manner

If on your distribution (eg. SteamOS) can be difficult to install something and keep it between updates, then you could use this script to install podman in your $HOME.

This has some limitations, for starters, it won't work in rootful mode for now, but otherwise it's working for normal use.

This is particularly indicated also for completely sudoless setups, where you don't have any superuser access to the system, like for example company provided computers.

Run:

curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/extras/install-podman | sh -s -- --prefix ~/.local

Provided the only dependency on the host (newuidmap/newgidmap, of the package uidmap), you should be good to go.

To uninstall:

curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/extras/install-podman | sh -s -- --prefix ~/.local --remove

Warning Remember to add ~/.local/podman/bin to your PATH, to make it work. Remember to add ~/.local/podman/bin to your ~/.distroboxrc also.

Compatibility notes

If your container is not able to connect to your host xserver, make sure to install xhost on the host machine and run xhost +si:localuser:$USER. If you wish to enable this functionality on future reboots add it to your ~/.xinitrc or somewhere else tailored to your use case where it would be ran on every startup.

Non shared mounts

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.

List of distributions including distrobox in their repositories

Packaging status

New Host 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!


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
Alpine (Toolbox) 3.16
3.17
edge
quay.io/toolbx-images/alpine-toolbox:3.16
quay.io/toolbx-images/alpine-toolbox:3.17
quay.io/toolbx-images/alpine-toolbox:edge
Archlinux (Toolbox) quay.io/toolbx-images/archlinux-toolbox
Centos (Toolbox) stream8
stream9
quay.io/toolbx-images/centos-toolbox:stream8
quay.io/toolbx-images/centos-toolbox:stream9
Debian (Toolbox) 10
11
testing
unstable
quay.io/toolbx-images/debian-toolbox:10
quay.io/toolbx-images/debian-toolbox:11
quay.io/toolbx-images/debian-toolbox:testing
quay.io/toolbx-images/debian-toolbox:unstable
Fedora (Toolbox) 36
37
38
39
Rawhide
registry.fedoraproject.org/fedora-toolbox: 37
registry.fedoraproject.org/fedora-toolbox:38
registry.fedoraproject.org/fedora-toolbox:39
openSUSE (Toolbox) registry.opensuse.org/opensuse/distrobox:latest
quay.io/toolbx-images/opensuse-toolbox: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
Ubuntu (Toolbox) 16.04
18.04
20.04
22.04
quay.io/toolbx-images/ubuntu-toolbox:16.04
quay.io/toolbx-images/ubuntu-toolbox:18.04
quay.io/toolbx-images/ubuntu-toolbox:20.04
quay.io/toolbx-images/ubuntu-toolbox:22.04
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
Chainguard Wolfi Small note: sudo is missing, use su-exec instead. cgr.dev/chainguard/wolfi-base:latest
ClearLinux docker.io/library/clearlinux:latest
docker.io/library/clearlinux:base
Crystal Linux registry.getcryst.al/crystal/misc/docker:latest
Debian 7
8
9
10
11
docker.io/debian/eol:wheezy
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
deepin 20 (apricot)
23 (beige)
docker.io/linuxdeepin/apricot
docker.io/linuxdeepin/beige
Fedora 36
37
38
39
Rawhide
quay.io/fedora/fedora:36
registry.fedoraproject.org/fedora:37
quay.io/fedora/fedora:38
quay.io/fedora/fedora:39
Gentoo Linux rolling docker.io/gentoo/stage3:latest
Kali Linux rolling docker.io/kalilinux/kali-rolling:latest
Mageia 8 docker.io/library/mageia
Mint 21.1 docker.io/linuxmintd/mint21.1-amd64
Neurodebian nd100 docker.io/library/neurodebian:nd100
openEULER docker.io/openeuler/openeuler:latest
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
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
Void Linux ghcr.io/void-linux/void-linux:latest-full-x86_64
ghcr.io/void-linux/void-linux:latest-full-x86_64-musl

Images marked with Toolbox are tailored 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

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.