1DISTROBOX(1) User Manual DISTROBOX(1)
2
6 This project does not need a dedicated image. It can use any OCI im‐
7 ages from docker-hub, quay.io, or any registry of your choice.
8 Many cloud images are stripped down on purpose to save size and may not
10 include commands such as which, mount, less or vi). Additional pack‐
11 ages can be installed once inside the container. We recommend using
12 your preferred automation tool inside the container if you find your‐
13 self having to repeatedly create new containers. Maintaining your own
14 custom image is also an option.
15 The main concern is having basic Linux utilities (mount), basic user
17 management utilities (usermod, passwd), and sudo correctly set.
18 SUPPORTED CONTAINER MANAGERS
20 distrobox can run on either podman, docker or lilipod
21 (https://github.com/89luca89/lilipod)
22 It depends either on podman configured in rootless mode or on docker
24 configured without sudo (follow THESE instructions (https://docs.dock‐
25 er.com/engine/install/linux-postinstall/))
26 • Minimum podman version: 2.1.0
28 • Minimum docker client version: 19.03.15
30 • Minimum lilipod version: v0.0.1
32 Follow the official installation guide here:
34 • <https://podman.io/getting-started/installation>
36 • <https://docs.docker.com/engine/install>
38 • <https://docs.docker.com/engine/install/linux-postinstall/>
40 CONTAINERS DISTROS
42 Distrobox guests tested successfully with the following container im‐
43 ages:
44 Distro Version Images
46 ──────────────────────────────────────────────────────────────────────────────
47 AlmaLinux (Toolbox) 8 9 quay.io/toolbx-im‐
48 ages/almalinux-tool‐
49 box:8 quay.io/toolbx-
50 images/almalinux-tool‐
51 box:9 quay.io/toolbx-
52 images/almalinux-tool‐
53 box:latest
54 Alpine (Toolbox) 3.16 3.17 3.18 edge quay.io/toolbx-im‐
55 ages/alpine-tool‐
56 box:3.16 quay.io/tool‐
57 bx-images/alpine-tool‐
58 box:3.17 quay.io/tool‐
59 bx-images/alpine-tool‐
60 box:3.18 quay.io/tool‐
61 bx-images/alpine-tool‐
62 box:edge quay.io/tool‐
63 bx-images/alpine-tool‐
64 box:latest
65 AmazonLinux (Toolbox) 2 2022 quay.io/toolbx-im‐
68 ages/amazonlinux-tool‐
69 box:2 quay.io/toolbx-
70 images/amazonlinux-
71 toolbox:2023
72 quay.io/toolbx-im‐
73 ages/amazonlinux-tool‐
74 box:latest
75 Archlinux (Toolbox) quay.io/toolbx-im‐
76 ages/archlinux-tool‐
77 box:latest
78 Bazzite Arch ghcr.io/ublue-os/bazz‐
79 ite-arch:latest
80 ghcr.io/ublue-os/bazz‐
81 ite-arch-gnome:latest
82 Centos (Toolbox) stream8 stream9 quay.io/toolbx-im‐
83 ages/centos-tool‐
84 box:stream8
85 quay.io/toolbx-im‐
86 ages/centos-tool‐
87 box:stream9
88 quay.io/toolbx-im‐
89 ages/centos-tool‐
90 box:latest
91 Debian (Toolbox) 10 11 12 testing unsta‐ quay.io/toolbx-im‐
92 ble ages/debian-toolbox:10
93 quay.io/toolbx-im‐
94 ages/debian-toolbox:11
95 quay.io/toolbx-im‐
96 ages/debian-toolbox:12
97 quay.io/toolbx-im‐
98 ages/debian-tool‐
99 box:testing
100 quay.io/toolbx-im‐
101 ages/debian-toolbox:un‐
102 stable quay.io/toolbx-
103 images/debian-tool‐
104 box:latest
105 Fedora (Toolbox) 36 37 38 39 Rawhide registry.fedorapro‐
106 ject.org/fedora-tool‐
107 box:37 registry.fedo‐
108 raproject.org/fedora-
109 toolbox:38 registry.fe‐
110 doraproject.org/fedora-
111 toolbox:39 registry.fe‐
112 doraproject.org/fedora-
113 toolbox:latest
114 openSUSE (Toolbox) registry.open‐
115 suse.org/opensuse/dis‐
116 trobox:latest
117 quay.io/toolbx-im‐
118 ages/opensuse-tool‐
119 box:tumbleweed
120 quay.io/toolbx-im‐
121 ages/opensuse-tool‐
122 box:latest
123 RedHat (Toolbox) 8 9 registry.access.red‐
124 hat.com/ubi8/toolbox
125 registry.access.red‐
126 hat.com/ubi9/toolbox
127 quay.io/toolbx-im‐
128 ages/rhel-toolbox:lat‐
129 est
130 Rocky Linux (Toolbox) 8 9 quay.io/toolbx-im‐
134 ages/rockylinux-tool‐
135 box:8 quay.io/toolbx-
136 images/rockylinux-tool‐
137 box:9 quay.io/toolbx-
138 images/rockylinux-tool‐
139 box:latest
140 Ubuntu (Toolbox) 16.04 18.04 20.04 22.04 quay.io/toolbx-im‐
141 ages/ubuntu-tool‐
142 box:16.04 quay.io/tool‐
143 bx-images/ubuntu-tool‐
144 box:18.04 quay.io/tool‐
145 bx-images/ubuntu-tool‐
146 box:20.04 quay.io/tool‐
147 bx-images/ubuntu-tool‐
148 box:22.04 quay.io/tool‐
149 bx-images/ubuntu-tool‐
150 box:latest
151 AlmaLinux (UBI) 8 quay.io/almalin‐
153 ux/8-base:8 quay.io/al‐
154 malinux/8-init:8
155 AlmaLinux 8 8-minimal 9 9-minimal quay.io/almalinux/alma‐
156 linux:8 quay.io/almal‐
157 inux/almalinux:9
158 quay.io/almalinux/alma‐
159 linux:9-minimal
160 Alpine Linux 3.15 3.16 docker.io/li‐
161 brary/alpine:3.15 dock‐
162 er.io/li‐
163 brary/alpine:3.16 dock‐
164 er.io/li‐
165 brary/alpine:latest
166 AmazonLinux 1 2 2023 public.ecr.aws/amazon‐
167 linux/amazonlinux:1
168 public.ecr.aws/amazon‐
169 linux/amazonlinux:2
170 public.ecr.aws/amazon‐
171 linux/amazonlinux:2023
172 Archlinux docker.io/library/arch‐
173 linux:latest
174 CentOS Stream 8 9 quay.io/centos/cen‐
175 tos:stream8
176 quay.io/centos/cen‐
177 tos:stream9
178 CentOS 7 quay.io/centos/centos:7
179 Chainguard Wolfi Small note: sudo is cgr.dev/chain‐
180 missing, use su-exec guard/wolfi-base:latest
181 instead.
182 ClearLinux docker.io/li‐
183 brary/clearlinux:latest
184 docker.io/li‐
185 brary/clearlinux:base
186 Crystal Linux reg‐
187 istry.getcryst.al/crys‐
188 tal/misc/docker:latest
189 Debian 7 8 9 10 11 12 docker.io/de‐
200 bian/eol:wheezy dock‐
201 er.io/library/de‐
202 bian:buster-backports
203 docker.io/library/de‐
204 bian:bullseye-backports
205 docker.io/library/de‐
206 bian:bookworm-backports
207 docker.io/library/de‐
208 bian:stable-backports
209 Debian Testing docker.io/library/de‐
210 bian:testing dock‐
211 er.io/library/de‐
212 bian:testing-backports
213 Debian Unstable docker.io/library/de‐
214 bian:unstable
215 deepin 20 (apricot) 23 (beige) docker.io/lin‐
216 uxdeepin/apricot dock‐
217 er.io/linuxdeepin/beige
218 Fedora 36 37 38 39 Rawhide quay.io/fedora/fedo‐
219 ra:36 registry.fedo‐
220 raproject.org/fedora:37
221 quay.io/fedora/fedo‐
222 ra:38 quay.io/fedo‐
223 ra/fedora:39
224 Gentoo Linux rolling docker.io/gen‐
225 too/stage3:latest
226 KDE neon Latest Testing Unstable invent-reg‐
227 istry.kde.org/neon/dock‐
228 er-images/plasma:latest
229 invent-reg‐
230 istry.kde.org/neon/dock‐
231 er-images/plasma:test‐
232 ing invent-reg‐
233 istry.kde.org/neon/dock‐
234 er-images/plasma:unsta‐
235 ble
236 Kali Linux rolling docker.io/kalilin‐
237 ux/kali-rolling:latest
238 Mint 21.1 docker.io/lin‐
239 uxmintd/mint21.1-amd64
240 Neurodebian nd100 docker.io/library/neu‐
241 rodebian:nd100
242 openSUSE Leap registry.open‐
243 suse.org/open‐
244 suse/leap:latest
245 openSUSE Tumbleweed registry.open‐
246 suse.org/opensuse/dis‐
247 trobox:latest reg‐
248 istry.opensuse.org/open‐
249 suse/tumbleweed:latest
250 registry.open‐
251 suse.org/opensuse/tool‐
252 box:latest
253 Oracle Linux 7 7-slim 8 8-slim 9 container-registry.ora‐
266 9-slim cle.com/os/oraclelinux:7
267 container-registry.ora‐
268 cle.com/os/oraclelin‐
269 ux:7-slim container-reg‐
270 istry.oracle.com/os/ora‐
271 clelinux:8 container-
272 registry.ora‐
273 cle.com/os/oraclelin‐
274 ux:8-slim container-reg‐
275 istry.oracle.com/os/ora‐
276 clelinux:9 container-
277 registry.ora‐
278 cle.com/os/oraclelin‐
279 ux:9-slim
280 RedHat (UBI) 7 8 9 registry.access.red‐
281 hat.com/ubi7/ubi reg‐
282 istry.access.red‐
283 hat.com/ubi7/ubi-init
284 registry.access.red‐
285 hat.com/ubi8/ubi reg‐
286 istry.access.red‐
287 hat.com/ubi8/ubi-init
288 registry.access.red‐
289 hat.com/ubi8/ubi-minimal
290 registry.access.red‐
291 hat.com/ubi9/ubi reg‐
292 istry.access.red‐
293 hat.com/ubi9/ubi-init
294 registry.access.red‐
295 hat.com/ubi9/ubi-minimal
296 Rocky Linux 8 8-minimal 9 quay.io/rockylinux/rock‐
297 ylinux:8 quay.io/rock‐
298 ylinux/rockylinux:8-min‐
299 imal quay.io/rockylin‐
300 ux/rockylinux:9
301 quay.io/rockylinux/rock‐
302 ylinux:latest
303 Scientific Linux 7 docker.io/library/sl:7
304 Slackware 14.2 docker.io/vbatts/slack‐
305 ware:14.2
306 Ubuntu 14.04 16.04 18.04 20.04 docker.io/library/ubun‐
307 22.04 23.04 tu:14.04 docker.io/li‐
308 brary/ubuntu:16.04 dock‐
309 er.io/library/ubun‐
310 tu:18.04 docker.io/li‐
311 brary/ubuntu:20.04 dock‐
312 er.io/library/ubun‐
313 tu:22.04
314 Vanilla OS VSO ghcr.io/vanilla-
315 os/vso:main
316 Void Linux ghcr.io/void-linux/void-
317 glibc-full:latest
318 Images marked with Toolbox are tailored images made by the community
320 efforts in toolbx-images/images (https://github.com/toolbx-images/im‐
321 ages), so they are more indicated for desktop use, and first setup will
322 take less time. Note however that if you use a non-toolbox preconfig‐
323 ured image, the first distrobox-enter you’ll perform can take a while
324 as it will download and install the missing dependencies.
325 A small time tax to pay for the ability to use any type of image. This
327 will not occur after the first time, subsequent enters will be much
328 faster.
329 NixOS is not a supported container distro, and there are currently no
331 plans to bring support to it. If you are looking for unprivileged
332 NixOS environments, we suggest you look into nix-shell
333 (https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html) or
334 nix portable (https://github.com/DavHau/nix-portable)
335 NEW DISTRO SUPPORT
337 If your distro of choice is not on the list, open an issue requesting
338 support for it, we can work together to check if it is possible to add
339 support for it.
340 Or just try using it anyway, if it works, open an issue and it will be
342 added to the list!
343 OLDER DISTRIBUTIONS
345 For older distributions like CentOS 5, CentOS 6, Debian 6, Ubuntu
346 12.04, compatibility is not assured.
347 Their libc version is incompatible with kernel releases after >=4.11.
349 A work around this is to use the vsyscall=emulate flag in the bootload‐
350 er of the host.
351 Keep also in mind that mirrors could be down for such old releases, so
353 you will need to build a custom distrobox image to ensure basic depen‐
354 dencies are met.
355 GPU ACCELERATION SUPPORT
357 For Intel and AMD Gpus, the support is baked in, as the containers will
358 install their latest available mesa/dri drivers.
359 For NVidia, you can use the --nvidia flag during create, see distrobox-
361 create documentation to discover how to use it.
362 Alternatively, you can use the nvidia-container-toolkit utility to set
364 up the integration independently from the distrobox’s own flag.
365Distrobox Nov 2023 DISTROBOX(1)