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 Granted, they may not be as featureful as expected (some of them do not
10 even have which, mount, less or vi) but that’s all doable in the con‐
11 tainer itself after bootstrapping it.
12 The main concern is having basic Linux utilities (mount), basic user
14 management utilities (usermod, passwd), and sudo correctly set.
15 Supported container managers
17 distrobox can run on either podman or docker
18 It depends either on podman configured in rootless mode or on docker
20 configured without sudo (follow THIS instructions (https://docs.dock‐
21 er.com/engine/install/linux-postinstall/))
22 • Minimum podman version: 2.1.0
24 • Minimum docker version: 18.06.1
26 Follow the official installation guide here:
28 • <https://podman.io/getting-started/installation>
30 • <https://docs.docker.com/engine/install>
32 • <https://docs.docker.com/engine/install/linux-postinstall/>
34 Containers Distros
36 Distrobox guests tested successfully with the following container im‐
37 ages:
38 Distro Version Images
40 ─────────────────────────────────────────────────────────────────────────────
41 AlmaLinux 8 8-minimal 9 9-minimal docker.io/library/alma‐
42 linux:8 docker.io/li‐
43 brary/almalinux:9 dock‐
44 er.io/library/almalin‐
45 ux:9-minimal
46 AlmaLinux (UBI) 8 docker.io/almalin‐
47 ux/8-base docker.io/al‐
48 malinux/8-init
49 Alpine Linux 3.14 3.15 docker.io/li‐
50 brary/alpine:latest
51 AmazonLinux 2 docker.io/library/ama‐
52 zonlinux:2.0.20211005.0
53 AmazonLinux 2022 public.ecr.aws/amazon‐
54 linux/amazonlinux:2022
55 Archlinux docker.io/library/arch‐
56 linux:latest
57 ClearLinux docker.io/li‐
58 brary/clearlinux:latest
59 docker.io/li‐
60 brary/clearlinux:base
61 CentOS 7 quay.io/centos/centos:7
62 CentOS Stream 8 9 quay.io/centos/cen‐
63 tos:stream8
64 quay.io/centos/cen‐
65 tos:stream9
66 RedHat (UBI) 7 8 9 registry.access.red‐
68 hat.com/ubi7/ubi reg‐
69 istry.access.red‐
70 hat.com/ubi7/ubi-init
71 registry.access.red‐
72 hat.com/ubi7/ubi-mini‐
73 mal registry.ac‐
74 cess.red‐
75 hat.com/ubi8/ubi reg‐
76 istry.access.red‐
77 hat.com/ubi8/ubi-init
78 registry.access.red‐
79 hat.com/ubi8/ubi-mini‐
80 mal registry.ac‐
81 cess.red‐
82 hat.com/ubi9/ubi reg‐
83 istry.access.red‐
84 hat.com/ubi9/ubi-init
85 registry.access.red‐
86 hat.com/ubi9/ubi-mini‐
87 mal
88 Debian 7 8 9 10 11 docker.io/de‐
89 bian/eol:wheezy dock‐
90 er.io/library/debian:8
91 docker.io/library/de‐
92 bian:9 docker.io/li‐
93 brary/debian:10 dock‐
94 er.io/library/de‐
95 bian:stable dock‐
96 er.io/library/de‐
97 bian:stable-backports
98 Debian Testing docker.io/library/de‐
99 bian:testing dock‐
100 er.io/library/de‐
101 bian:testing-backports
102 Debian Unstable docker.io/library/de‐
103 bian:unstable
104 Neurodebian nd100 docker.io/library/neu‐
105 rodebian:nd100
106 Fedora 34 35 36 37 Rawhide registry.fedorapro‐
107 ject.org/fedora-tool‐
108 box:34 docker.io/li‐
109 brary/fedora:34 reg‐
110 istry.fedorapro‐
111 ject.org/fedora-tool‐
112 box:35 docker.io/li‐
113 brary/fedora:35 dock‐
114 er.io/library/fedora:36
115 registry.fedorapro‐
116 ject.org/fedora:37
117 docker.io/library/fedo‐
118 ra:rawhide
119 Mageia 8 docker.io/li‐
120 brary/mageia
121 Opensuse Leap registry.open‐
122 suse.org/open‐
123 suse/leap:latest
124 Opensuse Tumbleweed registry.open‐
125 suse.org/opensuse/tum‐
126 bleweed:latest reg‐
127 istry.open‐
128 suse.org/opensuse/tool‐
129 box:latest
130 Oracle Linux 7 8 container-registry.ora‐
134 cle.com/os/oraclelin‐
135 ux:7 container-reg‐
136 istry.oracle.com/os/or‐
137 aclelinux:8
138 Rocky Linux 8 docker.io/rockylin‐
139 ux/rockylinux:8
140 Scientific Linux 7 docker.io/library/sl:7
141 Slackware 14.2 docker.io/vbatts/slack‐
142 ware:14.2
143 Ubuntu 14.04 16.04 18.04 20.04 docker.io/library/ubun‐
144 21.10 22.04 tu:14.04 docker.io/li‐
145 brary/ubuntu:16.04
146 docker.io/library/ubun‐
147 tu:18.04 docker.io/li‐
148 brary/ubuntu:20.04
149 docker.io/library/ubun‐
150 tu:21.10 docker.io/li‐
151 brary/ubuntu:22.04
152 Kali Linux rolling docker.io/kalilin‐
153 ux/kali-rolling:latest
154 Void Linux ghcr.io/void-lin‐
155 ux/void-linux:latest-
156 full-x86_64
157 ghcr.io/void-lin‐
158 ux/void-linux:latest-
159 full-x86_64-musl
160 Gentoo Linux rolling You will have to Build
161 your own to have a com‐
162 plete Gentoo docker im‐
163 age
164 Note however that if you use a non-toolbox preconfigured image (e.g.
166 images pre-baked to work with <https://github.com/containers/toolbox),>
167 the first distrobox-enter you’ll perform can take a while as it will
168 download and install the missing dependencies.
169 A small time tax to pay for the ability to use any type of image. This
171 will not occur after the first time, subsequent enters will be much
172 faster.
173 NixOS is not a supported container distro, and there are currently no
175 plans to bring support to it. If you are looking for unprivlaged NixOS
176 environments, we suggest you look into nix-shell
177 (https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html).
178 New Distro support
180 If your distro of choice is not on the list, open an issue requesting
181 support for it, we can work together to check if it is possible to add
182 support for it.
183 Or just try using it anyway, if it works, open an issue and it will be
185 added to the list!
186 Older distributions
188 For older distributions like CentOS 5, CentOS 6, Debian 6, Ubuntu
189 12.04, compatibility is not assured.
190 Their libc version is incompatible with kernel releases after >=4.11.
192 A work around this is to use the vsyscall=emulate flag in the bootload‐
193 er of the host.
194 Keep also in mind that mirrors could be down for such old releases, so
196 you will need to build a custom distrobox image to ensure basic depen‐
197 dencies are met.
198DISTROBOX-CREATE(1) User Manual DISTROBOX-CREATE(1)
200
204 distrobox-create takes care of creating the container with input name
205 and image. The created container will be tightly integrated with the
206 host, allowing sharing of the HOME directory of the user, external
207 storage, external usb devices and graphical apps (X11/Wayland), and au‐
208 dio.
209 Usage:
211 distrobox create --image alpine:latest --name test --init-hooks "touch /var/tmp/test1 && touch /var/tmp/test2"
213 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR-value"
214 distrobox create --image fedora:35 --name test --volume /opt/my-dir:/usr/local/my-dir:rw --additional-flags "--pids-limit -1"
215 distrobox create -i docker.io/almalinux/8-init --init --name test --pre-init-hooks "dnf config-manager --enable powertools && dnf -y install epel-release"
216 distrobox create --clone fedora-35 --name fedora-35-copy
217 distrobox create --image alpine my-alpine-container
218 distrobox create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
219 distrobox create --pull --image centos:stream9 --home ~/distrobox/centos9
220 You can also use environment variables to specify container name, image
222 and container manager:
223 DBX_CONTAINER_MANAGER="docker" DBX_NON_INTERACTIVE=1 DBX_CONTAINER_NAME=test-alpine DBX_CONTAINER_IMAGE=alpine distrobox-create
225 Supported environment variables:
227 DBX_CONTAINER_ALWAYS_PULL
229 DBX_CONTAINER_CUSTOM_HOME
230 DBX_CONTAINER_IMAGE
231 DBX_CONTAINER_MANAGER
232 DBX_CONTAINER_NAME
233 DBX_NON_INTERACTIVE
234 Options:
236 --image/-i: image to use for the container default: registry.fedoraproject.org/fedora-toolbox:36
238 --name/-n: name for the distrobox default: my-distrobox
239 --pull/-p: pull latest image unconditionally without asking
240 --yes/-Y: non-interactive, pull images without asking
241 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
242 way over "sudo distrobox"
243 --clone/-c: name of the distrobox container to use as base for a new container
244 this will be useful to either rename an existing distrobox or have multiple copies
245 of the same environment.
246 --home/-H select a custom HOME directory for the container. Useful to avoid host's home littering with temp files.
247 --volume additional volumes to add to the container
248 --additional-flags/-a: additional flags to pass to the container manager command
249 --init-hooks additional commands to execute during container initialization
250 --pre-init-hooks additional commands to execute prior to container initialization
251 --init/-I use init system (like systemd) inside the container.
252 this will make host's processes not visible from within the container.
253 --help/-h: show this message
254 --dry-run/-d: only print the container manager command generated
255 --verbose/-v: show more verbosity
256 --version/-V: show version
257 Compatibility:
259 for a list of compatible images and container managers, please consult the man page:
261 man distrobox
262 man distrobox-compatibility
263 or consult the documentation page on: https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros
264 The --additional-flags or -a is useful to modify defaults in the con‐
266 tainer creations. For example:
267 distrobox create -i docker.io/library/archlinux -n dev-arch
269 podman container inspect dev-arch | jq '.[0].HostConfig.PidsLimit'
271 2048
272 distrobox rm -f dev-arch
274 distrobox create -i docker.io/library/archlinux -n dev-arch --volume $CBL_TC:/tc --additional-flags "--pids-limit -1"
275 podman container inspect dev-arch | jq '.[0].HostConfig,.PidsLimit'
277 0
278 Additional volumes can be specified using the --volume flag. This flag
280 follows the same standard as docker and podman to specify the mount
281 point so --volume SOURCE_PATH:DEST_PATH:MODE.
282 distrobox create --image docker.io/library/archlinux --name dev-arch --volume /usr/share/:/var/test:ro
284 During container creation, it is possible to specify (using the addi‐
286 tional-flags) some environment variables that will persist in the con‐
287 tainer and be independent from your environment:
288 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR-value"
290 The --init-hooks is useful to add commands to the entrypoint (init) of
292 the container. This could be useful to create containers with a set of
293 programs already installed, add users, groups.
294 distrobox create --image fedora:35 --name test --init-hooks "dnf groupinstall -y \"C Development Tools and Libraries\""
296 The --init is useful to create a container that will use its own sepa‐
298 rate init system within. For example using:
299 distrobox create -i docker.io/almalinux/8-init --init-hooks "dnf install -y openssh-server" --init --name test
301 Inside the container we will be able to use normal systemd units:
303 ~$ distrobox enter test
305 user@test:~$ sudo systemctl enable --now sshd
306 user@test:~$ sudo systemctl status sshd
307 ● sshd.service - OpenSSH server daemon
308 Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)
309 Active: active (running) since Fri 2022-01-28 22:54:50 CET; 17s ago
310 Docs: man:sshd(8)
311 man:sshd_config(5)
312 Main PID: 291 (sshd)
313 Note that enabling --init will disable host’s process integration.
315 From within the container you will not be able to see and manage host’s
316 processes. This is needed because /sbin/init must be pid 1.
317DISTROBOX-ENTER(1) User Manual DISTROBOX-ENTER(1)
321
325 distrobox-enter takes care of entering the container with the name
326 specified. Default command executed is your SHELL, but you can specify
327 different shells or entire commands to execute. If using it inside a
328 script, an application, or a service, you can specify the –headless
329 mode to disable tty and interactivity.
330 Usage:
332 distrobox-enter --name fedora-toolbox-35 -- bash -l
334 distrobox-enter my-alpine-container -- sh -l
335 distrobox-enter --additional-flags "--preserve-fds" --name test -- bash -l
336 distrobox-enter --additional-flags "--env MY_VAR=value" --name test -- bash -l
337 MY_VAR=value distrobox-enter --additional-flags "--preserve-fds" --name test -- bash -l
338 You can also use environment variables to specify container manager and
340 container name:
341 DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-enter
343 Supported environment variables:
345 DBX_CONTAINER_NAME
347 DBX_CONTAINER_MANAGER
348 DBX_SKIP_WORKDIR
349 Options:
351 --name/-n: name for the distrobox default: my-distrobox
353 --/-e: end arguments execute the rest as command to execute at login default: bash -l
354 --no-tty/-T: do not instantiate a tty
355 --no-workdir/-nw: always start the container from container's home directory
356 --additional-flags/-a: additional flags to pass to the container manager command
357 --help/-h: show this message
358 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
359 way over "sudo distrobox"
360 --dry-run/-d: only print the container manager command generated
361 --verbose/-v: show more verbosity
362 --version/-V: show version
363 This is used to enter the distrobox itself. Personally, I just create
365 multiple profiles in my gnome-terminal to have multiple distros acces‐
366 sible.
367 The --additional-flags or -a is useful to modify default command when
369 executing in the container. For example:
370 distrobox enter -n dev-arch --additional-flags "--env my_var=test" -- printenv &| grep my_var
372 my_var=test
373 This is possible also using normal env variables:
375 my_var=test distrobox enter -n dev-arch --additional-flags -- printenv &| grep my_var
377 my_var=test
378DISTROBOX-EXPORT(1) User Manual DISTROBOX-EXPORT(1)
382
386 distrobox-export takes care of exporting an app a binary or a service
387 from the container to the host.
388 The exported app will be easily available in your normal launcher and
390 it will automatically be launched from the container it is exported
391 from.
392 The exported services will be available in the host’s user’s systemd
394 session, so
395 systemctl --user status exported_service_name
397 will show the status of the service exported.
399 The exported binaries will be exported in the “–export-path” of choice
401 as a wrapper script that acts naturally both on the host and in the
402 container. Note that “–export-path” is NOT OPTIONAL, you have to ex‐
403 plicitly set it.
404 You can specify additional flags to add to the command, for example if
406 you want to export an electron app, you could add the “–foreground”
407 flag to the command:
408 distrobox-export --app atom --extra-flags "--foreground"
410 distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --extra-flags "-p"
411 distrobox-export --service syncthing --extra-flags "-allow-newer-config"
412 This works for services, binaries, and apps. Extra flags are only used
414 then the exported app, binary, or service is used from the host, using
415 them inside the container will not include them.
416 The option “–delete” will un-export an app, binary, or service.
418 distrobox-export --app atom --delete
420 distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --delete
421 distrobox-export --service syncthing --delete
422 distrobox-export --service nginx --delete
423 The option “–sudo” will launch the exported item as root inside the
425 distrobox.
426 Note you can use –app OR –bin OR –service but not together.
428 distrobox-export --service nginx --sudo
430 Usage:
432 distrobox-export --app mpv [--extra-flags "flags"] [--delete] [--sudo]
434 distrobox-export --service syncthing [--extra-flags "flags"] [--delete] [--sudo]
435 distrobox-export --bin /path/to/bin --export-path ~/.local/bin [--extra-flags "flags"] [--delete] [--sudo]
436 Options:
438 --app/-a: name of the application to export
440 --bin/-b: absolute path of the binary to export
441 --service/-s: name of the service to export
442 --delete/-d: delete exported application or service
443 --export-label/-el: label to add to exported application name.
444 Defaults to (on \$container_name)
445 --export-path/-ep: path where to export the binary
446 --extra-flags/-ef: extra flags to add to the command
447 --sudo/-S: specify if the exported item should be ran as sudo
448 --help/-h: show this message
449 --verbose/-v: show more verbosity
450 --version/-V: show version
451 You may want to install graphical applications or user services in your
453 distrobox. Using distrobox-export from inside the container will let
454 you use them from the host itself.
455 App export example:
457 distrobox-export --app abiword
459 This tool will simply copy the original .desktop files along with need‐
461 ed icons, add the prefix /usr/local/bin/distrobox-enter -n dis‐
462 trobox_name -e ... to the commands to run, and save them in your home
463 to be used directly from the host as a normal app.
464 Service export example:
466 distrobox-export --service syncthing --extra-flags "--allow-newer-config"
468 distrobox-export --service nginx --sudo
469 For services, it will similarly export the systemd unit inside the con‐
471 tainer to a systemctl --user service, prefixing the various ExecStart
472 ExecStartPre ExecStartPost ExecReload ExecStop ExecStopPost with the
473 distrobox-enter command prefix.
474 Binary export example:
476 distrobox-export --bin /usr/bin/code --extra-flags "--foreground" --export-path $HOME/.local/bin
478 In the case of exporting binaries, you will have to specify where to
480 export it (--export-path) and the tool will create a little wrapper
481 script that will distrobox-enter -e from the host, the desired binary.
482 This can be handy with the use of direnv to have different versions of
483 the same binary based on your env or project.
484 [IMAGE: app-export (https://user-images.githubusercon‐
486 tent.com/598882/144294795-c7785620-bf68-4d1b-b251-1e1f0a32a08d.png)]
487 [IMAGE: service-export (https://user-images.githubusercon‐
489 tent.com/598882/144294314-29a8921f-4511-453d-bf8e-d0d1e336db91.png)]
490 NOTE: some electron apps such as vscode and atom need additional flags
492 to work from inside the container, use the --extra-flags option to pro‐
493 vide a series of flags, for example:
494 distrobox-export --app atom --extra-flags "--foreground"
496DISTROBOX-HOST-EXEC(1) User Manual DISTROBOX-HOST-EXEC(1)
500
504 distrobox-host-exec lets one execute command on the host, while inside
505 of a container.
506 If “flatpak-spawn” is installed in the container, this is what is used,
508 and it is the most powerful and recommended method. If, instead,
509 “flatpak-spawn” can’t be found, it still try to get the job done with
510 “chroot” (but beware that not all commands/programs will work well in
511 this mode).
512 Just pass to “distrobox-host-exec” any command and all its arguments,
514 if any.
515 distrobox-host-exec [command [arguments]]
517 If no command is provided, it will execute “/bin/sh”.
519 Example usage:
521 distrobox-host-exec ls
523 distrobox-host-exec bash -l
524 distrobox-host-exec flatpak run org.mozilla.firefox
525 distrobox-host-exec podman ps -a
526 Options:
528 --help/-h: show this message
530 --verbose/-v: show more verbosity
531 --version/-V: show version
532DISTROBOX-INIT(1) User Manual DISTROBOX-INIT(1)
536
540 distrobox-init is the entrypoint of a created distrobox. Note that
541 this HAS to run from inside a distrobox, will not work if you run it
542 from your host.
543 This is not intended to be used manually, but instead used by dis‐
545 trobox-enter to set up the container’s entrypoint.
546 distrobox-init will take care of installing missing dependencies (eg.
548 sudo), set up the user and groups, mount directories from the host to
549 ensure the tight integration.
550 Usage:
552 distrobox-init --name test-user --user 1000 --group 1000 --home /home/test-user
554 Options:
556 --name/-n: user name
558 --user/-u: uid of the user
559 --group/-g: gid of the user
560 --home/-d: path/to/home of the user
561 --help/-h: show this message
562 --init/-I: whether to use or not init
563 --pre-init-hooks: commands to execute prior to init
564 --verbose/-v: show more verbosity
565 --version/-V: show version
566 --: end arguments execute the rest as command to execute during init
567 This is used as entrypoint for the created container, it will take care
569 of creating the users, setting up sudo, mountpoints, and exports.
570 You should not have to launch this manually, this is used by distrobox
572 create to set up container’s entrypoint.
573DISTROBOX-LIST(1) User Manual DISTROBOX-LIST(1)
577
581 distrobox-list lists available distroboxes. It detects them and lists
582 them separately from the rest of normal podman or docker containers.
583 Usage:
585 distrobox-list
587 You can also use environment variables to specify container manager
589 DBX_CONTAINER_MANAGER="docker" distrobox-list
591 Supported environment variables:
593 DBX_CONTAINER_MANAGER
595 Options:
597 --help/-h: show this message
599 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
600 way over "sudo distrobox"
601 --size/-s: show also container size
602 --verbose/-v: show more verbosity
603 --version/-V: show version
604 [IMAGE: image (https://user-images.githubusercon‐
606 tent.com/598882/147831082-24b5bc2e-b47e-49ac-9b1a-a209478c9705.png)]
607DISTROBOX-RM(1) User Manual DISTROBOX-RM(1)
611
615 distrobox-rm delete one of the available distroboxes.
616 Usage:
618 distrobox-rm --name container-name [--force]
620 distrobox-rm container-name [-f]
621 You can also use environment variables to specify container manager and
623 name:
624 DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-rm
626 Supported environment variables:
628 DBX_CONTAINER_MANAGER
630 DBX_CONTAINER_NAME
631 DBX_NON_INTERACTIVE
632 Options:
634 --name/-n: name for the distrobox
636 --force/-f: force deletion
637 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
638 way over "sudo distrobox"
639 --help/-h: show this message
640 --verbose/-v: show more verbosity
641 --version/-V: show version
642DISTROBOX-STOP(1) User Manual DISTROBOX-STOP(1)
646
650 distrobox-stop stop a running distrobox.
651 Distroboxes are left running, even after exiting out of them, so that
653 subsequent enters are really quick. This is how they can be stopped.
654 Usage:
656 distrobox-stop --name container-name
658 distrobox-stop container-name
659 You can also use environment variables to specify container manager and
661 name:
662 DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-stop
664 Supported environment variables:
666 DBX_CONTAINER_MANAGER
668 DBX_CONTAINER_NAME
669 DBX_NON_INTERACTIVE
670 Options:
672 --name/-n: name for the distrobox
674 --yes/-Y: non-interactive, stop without asking
675 --help/-h: show this message
676 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
677 way over "sudo distrobox"
678 --verbose/-v: show more verbosity
679 --version/-V: show version
680Distrobox Jun 2022 DISTROBOX-STOP(1)