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 or docker
21 It depends either on podman configured in rootless mode or on docker
23 configured without sudo (follow THESE instructions (https://docs.dock‐
24 er.com/engine/install/linux-postinstall/))
25 • Minimum podman version: 2.1.0
27 • Minimum docker version: 18.06.1
29 Follow the official installation guide here:
31 • <https://podman.io/getting-started/installation>
33 • <https://docs.docker.com/engine/install>
35 • <https://docs.docker.com/engine/install/linux-postinstall/>
37 CONTAINERS DISTROS
39 Distrobox guests tested successfully with the following container im‐
40 ages:
41 Distro Version Images
43 ─────────────────────────────────────────────────────────────────────────────
44 AlmaLinux (UBI) 8 quay.io/almalin‐
45 ux/8-base:8 quay.io/al‐
46 malinux/8-init:8
47 AlmaLinux 8 8-minimal 9 9-minimal quay.io/almalinux/alma‐
48 linux:8 quay.io/almal‐
49 inux/almalinux:9
50 quay.io/almalinux/alma‐
51 linux:9-minimal
52 Alpine Linux 3.15 3.16 docker.io/li‐
53 brary/alpine:3.15 dock‐
54 er.io/li‐
55 brary/alpine:3.16 dock‐
56 er.io/li‐
57 brary/alpine:latest
58 AmazonLinux 1 2 2022 public.ecr.aws/amazon‐
59 linux/amazonlinux:1
60 public.ecr.aws/amazon‐
61 linux/amazonlinux:2
62 public.ecr.aws/amazon‐
63 linux/amazonlin‐
64 ux:2022.0.20220531.0
65 Archlinux docker.io/library/arch‐
68 linux:latest
69 CentOS Stream 8 9 quay.io/centos/cen‐
70 tos:stream8
71 quay.io/centos/cen‐
72 tos:stream9
73 CentOS 7 quay.io/centos/centos:7
74 ClearLinux docker.io/li‐
75 brary/clearlinux:latest
76 docker.io/li‐
77 brary/clearlinux:base
78 Debian 7 8 9 10 11 docker.io/de‐
79 bian/eol:wheezy dock‐
80 er.io/debian/eol:jessie
81 docker.io/library/de‐
82 bian:9 docker.io/li‐
83 brary/debian:10 dock‐
84 er.io/library/de‐
85 bian:stable dock‐
86 er.io/library/de‐
87 bian:stable-backports
88 Debian Testing docker.io/library/de‐
89 bian:testing dock‐
90 er.io/library/de‐
91 bian:testing-backports
92 Debian Unstable docker.io/library/de‐
93 bian:unstable
94 Fedora 35 36 37 38 Rawhide registry.fedorapro‐
95 ject.org/fedora-tool‐
96 box:37 quay.io/fedo‐
97 ra/fedora:35
98 quay.io/fedora/fedo‐
99 ra:36 registry.fedo‐
100 raproject.org/fedora:37
101 quay.io/fedora/fedo‐
102 ra:38
103 Gentoo Linux rolling docker.io/gen‐
104 too/stage3:latest
105 Kali Linux rolling docker.io/kalilin‐
106 ux/kali-rolling:latest
107 Mageia 8 docker.io/li‐
108 brary/mageia
109 Neurodebian nd100 docker.io/library/neu‐
110 rodebian:nd100
111 Opensuse Leap registry.open‐
112 suse.org/open‐
113 suse/leap:latest
114 Opensuse Tumbleweed registry.open‐
115 suse.org/opensuse/tum‐
116 bleweed:latest reg‐
117 istry.open‐
118 suse.org/opensuse/tool‐
119 box:latest
120 Oracle Linux 7 7-slim 8 8-slim 9 container-registry.ora‐
134 9-slim cle.com/os/oraclelin‐
135 ux:7 container-reg‐
136 istry.oracle.com/os/or‐
137 aclelinux:7-slim con‐
138 tainer-registry.ora‐
139 cle.com/os/oraclelin‐
140 ux:8 container-reg‐
141 istry.oracle.com/os/or‐
142 aclelinux:8-slim con‐
143 tainer-registry.ora‐
144 cle.com/os/oraclelin‐
145 ux:9 container-reg‐
146 istry.oracle.com/os/or‐
147 aclelinux:9-slim
148 RedHat (UBI) 7 8 9 registry.access.red‐
149 hat.com/ubi7/ubi reg‐
150 istry.access.red‐
151 hat.com/ubi7/ubi-init
152 registry.access.red‐
153 hat.com/ubi8/ubi reg‐
154 istry.access.red‐
155 hat.com/ubi8/ubi-init
156 registry.access.red‐
157 hat.com/ubi8/ubi-mini‐
158 mal registry.ac‐
159 cess.red‐
160 hat.com/ubi9/ubi reg‐
161 istry.access.red‐
162 hat.com/ubi9/ubi-init
163 registry.access.red‐
164 hat.com/ubi9/ubi-mini‐
165 mal
166 Rocky Linux 8 8-minimal 9 quay.io/rockylin‐
167 ux/rockylinux:8
168 quay.io/rockylin‐
169 ux/rockylinux:8-minimal
170 quay.io/rockylin‐
171 ux/rockylinux:9
172 quay.io/rockylin‐
173 ux/rockylinux:latest
174 Scientific Linux 7 docker.io/library/sl:7
175 Slackware 14.2 docker.io/vbatts/slack‐
176 ware:14.2
177 Ubuntu 14.04 16.04 18.04 20.04 docker.io/library/ubun‐
178 22.04 22.10 tu:14.04 docker.io/li‐
179 brary/ubuntu:16.04
180 docker.io/library/ubun‐
181 tu:18.04 docker.io/li‐
182 brary/ubuntu:20.04
183 docker.io/library/ubun‐
184 tu:22.04
185 Void Linux ghcr.io/void-lin‐
186 ux/void-linux:latest-
187 full-x86_64
188 ghcr.io/void-lin‐
189 ux/void-linux:latest-
190 full-x86_64-musl
191 Note however that if you use a non-toolbox preconfigured image (e.g.
193 images pre-baked to work with <https://github.com/containers/toolbox>),
194 the first distrobox-enter you’ll perform can take a while as it will
195 download and install the missing dependencies.
196 A small time tax to pay for the ability to use any type of image. This
198 will not occur after the first time, subsequent enters will be much
199 faster.
200 NixOS is not a supported container distro, and there are currently no
202 plans to bring support to it. If you are looking for unprivlaged NixOS
203 environments, we suggest you look into nix-shell
204 (https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html).
205 NEW DISTRO SUPPORT
207 If your distro of choice is not on the list, open an issue requesting
208 support for it, we can work together to check if it is possible to add
209 support for it.
210 Or just try using it anyway, if it works, open an issue and it will be
212 added to the list!
213 OLDER DISTRIBUTIONS
215 For older distributions like CentOS 5, CentOS 6, Debian 6, Ubuntu
216 12.04, compatibility is not assured.
217 Their libc version is incompatible with kernel releases after >=4.11.
219 A work around this is to use the vsyscall=emulate flag in the bootload‐
220 er of the host.
221 Keep also in mind that mirrors could be down for such old releases, so
223 you will need to build a custom distrobox image to ensure basic depen‐
224 dencies are met.
225DISTROBOX-CREATE(1) User Manual DISTROBOX-CREATE(1)
229
233 distrobox create
234 distrobox-create
235
237 distrobox-create takes care of creating the container with input name
238 and image. The created container will be tightly integrated with the
239 host, allowing sharing of the HOME directory of the user, external
240 storage, external usb devices and graphical apps (X11/Wayland), and au‐
241 dio.
242
244 distrobox create
245 --image/-i: image to use for the container default: registry.fedoraproject.org/fedora-toolbox:36
247 --name/-n: name for the distrobox default: my-distrobox
248 --pull/-p: pull latest image unconditionally without asking
249 --yes/-Y: non-interactive, pull images without asking
250 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
251 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
252 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
253 --clone/-c: name of the distrobox container to use as base for a new container
254 this will be useful to either rename an existing distrobox or have multiple copies
255 of the same environment.
256 --home/-H select a custom HOME directory for the container. Useful to avoid host's home littering with temp files.
257 --volume additional volumes to add to the container
258 --additional-flags/-a: additional flags to pass to the container manager command
259 --init-hooks additional commands to execute during container initialization
260 --pre-init-hooks additional commands to execute prior to container initialization
261 --init/-I use init system (like systemd) inside the container.
262 this will make host's processes not visible from within the container.
263 --compatibility/-C: show list of compatible images
264 --help/-h: show this message
265 --no-entry: do not generate a container entry in the application list
266 --dry-run/-d: only print the container manager command generated
267 --verbose/-v: show more verbosity
268 --version/-V: show version
269
271 for a list of compatible images and container managers, please consult the man page:
272 man distrobox
273 man distrobox-compatibility
274 or consult the documentation page on: https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros
275
277 distrobox create --image alpine:latest --name test --init-hooks "touch /var/tmp/test1 && touch /var/tmp/test2"
278 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR-value"
279 distrobox create --image fedora:35 --name test --volume /opt/my-dir:/usr/local/my-dir:rw --additional-flags "--pids-limit -1"
280 distrobox create -i docker.io/almalinux/8-init --init --name test --pre-init-hooks "dnf config-manager --enable powertools && dnf -y install epel-release"
281 distrobox create --clone fedora-35 --name fedora-35-copy
282 distrobox create --image alpine my-alpine-container
283 distrobox create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
284 distrobox create --pull --image centos:stream9 --home ~/distrobox/centos9
285 You can also use environment variables to specify container name, image
287 and container manager:
288 DBX_CONTAINER_MANAGER="docker" DBX_NON_INTERACTIVE=1 DBX_CONTAINER_NAME=test-alpine DBX_CONTAINER_IMAGE=alpine distrobox-create
290 Supported environment variables:
292 DBX_CONTAINER_ALWAYS_PULL
294 DBX_CONTAINER_CUSTOM_HOME
295 DBX_CONTAINER_HOME_PREFIX
296 DBX_CONTAINER_IMAGE
297 DBX_CONTAINER_MANAGER
298 DBX_CONTAINER_NAME
299 DBX_NON_INTERACTIVE
300 DBX_SUDO_PROGRAM
301 DBX_CONTAINER_HOME_PREFIX defines where containers’ home directories
303 will be located. If you define it as ~/dbx then all future containers’
304 home directories will be ~/dbx/$container_name
305 The --additional-flags or -a is useful to modify defaults in the con‐
307 tainer creations. For example:
308 distrobox create -i docker.io/library/archlinux -n dev-arch
310 podman container inspect dev-arch | jq '.[0].HostConfig.PidsLimit'
312 2048
313 distrobox rm -f dev-arch
315 distrobox create -i docker.io/library/archlinux -n dev-arch --volume $CBL_TC:/tc --additional-flags "--pids-limit -1"
316 podman container inspect dev-arch | jq '.[0].HostConfig,.PidsLimit'
318 0
319 Additional volumes can be specified using the --volume flag. This flag
321 follows the same standard as docker and podman to specify the mount
322 point so --volume SOURCE_PATH:DEST_PATH:MODE.
323 distrobox create --image docker.io/library/archlinux --name dev-arch --volume /usr/share/:/var/test:ro
325 During container creation, it is possible to specify (using the addi‐
327 tional-flags) some environment variables that will persist in the con‐
328 tainer and be independent from your environment:
329 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR-value"
331 The --init-hooks is useful to add commands to the entrypoint (init) of
333 the container. This could be useful to create containers with a set of
334 programs already installed, add users, groups.
335 distrobox create --image fedora:35 --name test --init-hooks "dnf groupinstall -y \"C Development Tools and Libraries\""
337 The --init is useful to create a container that will use its own sepa‐
339 rate init system within. For example using:
340 distrobox create -i docker.io/almalinux/8-init --init-hooks "dnf install -y openssh-server" --init --name test
342 Inside the container we will be able to use normal systemd units:
344 ~$ distrobox enter test
346 user@test:~$ sudo systemctl enable --now sshd
347 user@test:~$ sudo systemctl status sshd
348 ● sshd.service - OpenSSH server daemon
349 Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)
350 Active: active (running) since Fri 2022-01-28 22:54:50 CET; 17s ago
351 Docs: man:sshd(8)
352 man:sshd_config(5)
353 Main PID: 291 (sshd)
354 Note that enabling --init will disable host’s process integration.
356 From within the container you will not be able to see and manage host’s
357 processes. This is needed because /sbin/init must be pid 1.
358 The --home flag let’s you specify a custom HOME for the container.
360 Note that this will NOT prevent the mount of the host’s home directory,
361 but will ensure that configs and dotfiles will not litter it.
362 From version 1.4.0 of distrobox, when you create a new container, it
364 will also generate an entry in the applications list.
365DISTROBOX-ENTER(1) User Manual DISTROBOX-ENTER(1)
369
373 distrobox enter
374 distrobox-enter
375
377 distrobox-enter takes care of entering the container with the name
378 specified. Default command executed is your SHELL, but you can specify
379 different shells or entire commands to execute. If using it inside a
380 script, an application, or a service, you can specify the –headless
381 mode to disable tty and interactivity.
382
384 distrobox enter
385 --name/-n: name for the distrobox default: my-distrobox
387 --/-e: end arguments execute the rest as command to execute at login default: bash -l
388 --no-tty/-T: do not instantiate a tty
389 --no-workdir/-nw: always start the container from container's home directory
390 --additional-flags/-a: additional flags to pass to the container manager command
391 --help/-h: show this message
392 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
393 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
394 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
395 --dry-run/-d: only print the container manager command generated
396 --verbose/-v: show more verbosity
397 --version/-V: show version
398
400 distrobox-enter --name fedora-toolbox-35 -- bash -l
401 distrobox-enter my-alpine-container -- sh -l
402 distrobox-enter --additional-flags "--preserve-fds" --name test -- bash -l
403 distrobox-enter --additional-flags "--env MY_VAR=value" --name test -- bash -l
404 MY_VAR=value distrobox-enter --additional-flags "--preserve-fds" --name test -- bash -l
405 You can also use environment variables to specify container manager and
407 container name:
408 DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-enter
410 Supported environment variables:
412 DBX_CONTAINER_NAME
414 DBX_CONTAINER_MANAGER
415 DBX_SKIP_WORKDIR
416 DBX_SUDO_PROGRAM
417 This is used to enter the distrobox itself. Personally, I just create
419 multiple profiles in my gnome-terminal to have multiple distros acces‐
420 sible.
421 The --additional-flags or -a is useful to modify default command when
423 executing in the container. For example:
424 distrobox enter -n dev-arch --additional-flags "--env my_var=test" -- printenv &| grep my_var
426 my_var=test
427 This is possible also using normal env variables:
429 my_var=test distrobox enter -n dev-arch --additional-flags -- printenv &| grep my_var
431 my_var=test
432 If you’d like to enter a rootful container having distrobox use a pro‐
434 gram other than `sudo' to run podman/docker as root, such as `pkexec'
435 or `doas', you may specify it with the DBX_SUDO_PROGRAM environment
436 variable. For example, to use `doas' to enter a rootful container:
437 DBX_SUDO_PROGRAM="doas" distrobox enter -n container --root
439 Additionally, in one of the config file paths that distrobox supports,
441 such as ~/.distroboxrc, you can also append the line distrobox_su‐
442 do_program="doas" (for example) to always run distrobox commands in‐
443 volving rootful containers using `doas'.
444DISTROBOX-EPHEMERAL(1) User Manual DISTROBOX-EPHEMERAL(1)
448
452 distrobox ephemeral
453 distrobox-ephemeral
454
456 distrobox-ephemeral creates a temporary distrobox that is automatically
457 destroyed when the command is terminated.
458
460 distrobox ephemeral
461 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
463 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
464 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
465 --verbose/-v: show more verbosity
466 --help/-h: show this message
467 --/-e: end arguments execute the rest as command to execute at login default: bash -l
468 --version/-V: show version
469
471 distrobox-ephemeral --image alpine:latest -- cat /etc/os-release
472 distrobox-ephemeral --root --verbose --image alpine:latest --volume /opt:/opt
473 You can also use flags from distrobox-create to customize the ephemeral
475 container to run.
476 Refer to
478 man distrobox-create
480 or
482 distrobox-create --help
484 Supported environment variables:
486 distrobox-ephemeral calls distrobox-create, SEE ALSO distrobox-create(1) for
488 a list of supported environment variables to use.
489DISTROBOX-EXPORT(1) User Manual DISTROBOX-EXPORT(1)
493
497 distrobox-export
498
500 Application and service exporting
501 distrobox-export takes care of exporting an app a binary or a service
503 from the container to the host.
504 The exported app will be easily available in your normal launcher and
506 it will automatically be launched from the container it is exported
507 from.
508
510 distrobox-export
511 --app/-a: name of the application to export
513 --bin/-b: absolute path of the binary to export
514 --service/-s: name of the service to export
515 --delete/-d: delete exported application or service
516 --export-label/-el: label to add to exported application name.
517 Defaults to (on \$container_name)
518 --export-path/-ep: path where to export the binary
519 --extra-flags/-ef: extra flags to add to the command
520 --sudo/-S: specify if the exported item should be run as sudo
521 --help/-h: show this message
522 --verbose/-v: show more verbosity
523 --version/-V: show version
524 You may want to install graphical applications or user services in your
526 distrobox. Using distrobox-export from inside the container will let
527 you use them from the host itself.
528
530 distrobox-export --app mpv [--extra-flags "flags"] [--delete] [--sudo]
531 distrobox-export --service syncthing [--extra-flags "flags"] [--delete] [--sudo]
532 distrobox-export --bin /path/to/bin --export-path ~/.local/bin [--extra-flags "flags"] [--delete] [--sudo]
533 App export example
535 distrobox-export --app abiword
537 This tool will simply copy the original .desktop files along with need‐
539 ed icons, add the prefix /usr/local/bin/distrobox-enter -n dis‐
540 trobox_name -e ... to the commands to run, and save them in your home
541 to be used directly from the host as a normal app.
542 Service export example
544 distrobox-export --service syncthing --extra-flags "--allow-newer-config"
546 distrobox-export --service nginx --sudo
547 For services, it will similarly export the systemd unit inside the con‐
549 tainer to a systemctl --user service, prefixing the various ExecStart
550 ExecStartPre ExecStartPost ExecReload ExecStop ExecStopPost with the
551 distrobox-enter command prefix.
552 The exported services will be available in the host’s user’s systemd
554 session, so
555 systemctl --user status exported_service_name
557 will show the status of the service exported.
559 Binary export example
561 distrobox-export --bin /usr/bin/code --extra-flags "--foreground" --export-path $HOME/.local/bin
563 In the case of exporting binaries, you will have to specify where to
565 export it (--export-path) and the tool will create a little wrapper
566 script that will distrobox-enter -e from the host, the desired binary.
567 This can be handy with the use of direnv to have different versions of
568 the same binary based on your env or project.
569 The exported binaries will be exported in the “–export-path” of choice
571 as a wrapper script that acts naturally both on the host and in the
572 container. Note that “–export-path” is NOT OPTIONAL, you have to ex‐
573 plicitly set it.
574 Additional flags
576 You can specify additional flags to add to the command, for example if
578 you want to export an electron app, you could add the “–foreground”
579 flag to the command:
580 distrobox-export --app atom --extra-flags "--foreground"
582 distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --extra-flags "-p"
583 distrobox-export --service syncthing --extra-flags "-allow-newer-config"
584 This works for services, binaries, and apps. Extra flags are only used
586 then the exported app, binary, or service is used from the host, using
587 them inside the container will not include them.
588 Unexport
590 The option “–delete” will un-export an app, binary, or service.
592 distrobox-export --app atom --delete
594 distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --delete
595 distrobox-export --service syncthing --delete
596 distrobox-export --service nginx --delete
597 Run as root in the container
599 The option “–sudo” will launch the exported item as root inside the
601 distrobox.
602 Exporting apps from rootful containers
604 It is worth noting that, when exporting any item - which includes
606 graphical apps - from rootful containers (created with distrobox create
607 --root), root privileges will be needed every time the item is launched
608 (in order to enter the rootful container), which, by default, is done
609 using sudo (see docs for distrobox-enter on how to customize that).
610 However, for graphical apps in specific, since they launch without a
611 terminal, the usage of sudo might, at first, make it impossible to
612 launch them.
613 To fix this without needing to customize the sudo program, one can de‐
615 fine a global SUDO_ASKPASS environment variable on their machine, which
616 is a PATH to an executable that is run by sudo when no terminal is
617 available (or when it is given the --askpass or -A option), and the
618 output of that executable to stdout is used as the password input. The
619 executable is called as many times is needed for authentication as root
620 to succeed (unless a limit of amount of attempts is reached).
621 To do this, pick a program to ask the user for graphical password in‐
623 put. In this example, we will use zenity --password, which should be
624 present for GNOME users (and can also be installed in other DEs) -
625 there are other options, such as kdialog --password "Message" for KDE
626 users.
627 Write the call to the desired program to a script file, for example to
629 /usr/bin/my-password-prompt (sample contents below):
630 #!/bin/sh
632 zenity --password "Authentication as root is required"
633 (You may save the script under, for example, ~/.local/bin if you want
635 to keep it fully local to your user.)
636 Afterwards, make it executable (e.g. run sudo chmod +x /usr/bin/my-
638 password-prompt). Then, make sure to set SUDO_ASKPASS to "/usr/bin/my-
639 password-prompt" (replace with your script’s path) in a global profile
640 file, so that it is picked up by sudo when running graphical apps (and,
641 therefore, sudo will run the script you created to ask for a password).
642 This is done with the shell line export SU‐
643 DO_ASKPASS="/path/to/script/goes/here". You can do this for your user
644 only by running the command below (replace the script path as needed):
645 echo 'export SUDO_ASKPASS="/usr/bin/my-password-prompt"' >> ~/.profile
647 Which appends the appropriate line to the end of your ~/.profile file,
649 thus making the change local to your user. Alternatively, to set it
650 system-wide (for all users), you may create a file in /etc/profile.d/
651 (or equivalent for your system) with that line.
652 Now just log out and log back in, and graphical apps exported from
654 rootful containers should now be properly asking for root’s password
655 before launching (instead of not opening, if that was the case before).
656 Notes
658 Note you can use –app OR –bin OR –service but not together.
660 distrobox-export --service nginx --sudo
662 [IMAGE: app-export (https://user-images.githubusercon‐
664 tent.com/598882/144294795-c7785620-bf68-4d1b-b251-1e1f0a32a08d.png)]
665 [IMAGE: service-export (https://user-images.githubusercon‐
667 tent.com/598882/144294314-29a8921f-4511-453d-bf8e-d0d1e336db91.png)]
668 NOTE: some electron apps such as vscode and atom need additional flags
670 to work from inside the container, use the --extra-flags option to pro‐
671 vide a series of flags, for example:
672 distrobox-export --app atom --extra-flags "--foreground"
674DISTROBOX-GENERATE-ENTRY(1) User Manual DISTROBOX-GENERATE-ENTRY(1)
678
682 distrobox generate-entry
683
685 distrobox-generate-entry will create a desktop icon for one of the
686 available distroboxes. This will be then deleted when you remove the
687 matching distrobox.
688
690 distrobox generate-entry
691 --help/-h: show this message
693 --all/-a: perform for all distroboxes
694 --delete/-d: delete the entry
695 --icon/-i: specify a custom icon [/path/to/icon] (default auto)
696 --verbose/-v: show more verbosity
697 --version/-V: show version
698
700 distrobox-generate-entry container-name [--delete] [--icon [auto,/path/to/icon]]
701DISTROBOX-HOST-EXEC(1) User Manual DISTROBOX-HOST-EXEC(1)
705
709 distrobox-host-exec
710
712 distrobox-host-exec lets one execute command on the host, while inside
713 of a container.
714 Under the hood, distrobox-host-exec uses host-spawn a project that
716 let’s us execute commands back on the host. If the tool is not found
717 the user will be prompted to install it.
718
720 Just pass to “distrobox-host-exec” any command and all its arguments,
721 if any.
722 distrobox-host-exec [command [arguments]]
724 --help/-h: show this message
726 --verbose/-v: show more verbosity
727 --version/-V: show version
728 If no command is provided, it will execute “$SHELL”.
730 Alternatively, use symlinks to make distrobox-host-exec execute as that
732 command:
733 ~$: ln -s /usr/bin/distrobox-host-exec /usr/local/bin/podman
735 ~$: ls -l /usr/local/bin/podman
736 lrwxrwxrwx. 1 root root 51 Jul 11 19:26 /usr/local/bin/podman -> /usr/bin/distrobox-host-exec
737 ~$: podman version
738 ...this is executed on host...
739
741 distrobox-host-exec ls
742 distrobox-host-exec bash -l
743 distrobox-host-exec flatpak run org.mozilla.firefox
744 distrobox-host-exec podman ps -a
745DISTROBOX-INIT(1) User Manual DISTROBOX-INIT(1)
749
753 distrobox-init
754
756 Init the distrobox (not to be launched manually)
757 distrobox-init is the entrypoint of a created distrobox. Note that
759 this HAS to run from inside a distrobox, will not work if you run it
760 from your host.
761 This is not intended to be used manually, but instead used by dis‐
763 trobox-create to set up the container’s entrypoint.
764 distrobox-init will take care of installing missing dependencies (eg.
766 sudo), set up the user and groups, mount directories from the host to
767 ensure the tight integration.
768
770 distrobox-init
771 --name/-n: user name
773 --user/-u: uid of the user
774 --group/-g: gid of the user
775 --home/-d: path/to/home of the user
776 --help/-h: show this message
777 --init/-I: whether to use or not init
778 --pre-init-hooks: commands to execute prior to init
779 --upgrade/-U: run init in upgrade mode
780 --verbose/-v: show more verbosity
781 --version/-V: show version
782 --: end arguments execute the rest as command to execute during init
783
785 distrobox-init --name test-user --user 1000 --group 1000 --home /home/test-user
786 distrobox-init --upgrade
787DISTROBOX-LIST(1) User Manual DISTROBOX-LIST(1)
791
795 distrobox list
796 distrobox-list
797
799 distrobox-list lists available distroboxes. It detects them and lists
800 them separately from the rest of normal podman or docker containers.
801
803 distrobox list
804 --help/-h: show this message
806 --no-color: disable color formatting
807 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
808 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
809 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
810 --size/-s: show also container size
811 --verbose/-v: show more verbosity
812 --version/-V: show version
813
815 distrobox-list
816 You can also use environment variables to specify container manager
818 DBX_CONTAINER_MANAGER="docker" distrobox-list
820 Supported environment variables:
822 DBX_CONTAINER_MANAGER
824 DBX_SUDO_PROGRAM
825 [IMAGE: image (https://user-images.githubusercon‐
827 tent.com/598882/147831082-24b5bc2e-b47e-49ac-9b1a-a209478c9705.png)]
828DISTROBOX-RM(1) User Manual DISTROBOX-RM(1)
832
836 distrobox rm
837 distrobox-rm
838
840 distrobox-rm delete one of the available distroboxes.
841
843 distrobox rm
844 --name/-n: name for the distrobox
846 --force/-f: force deletion
847 --rm-home: remove the mounted home if it differs from the host user's one
848 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
849 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
850 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
851 --help/-h: show this message
852 --verbose/-v: show more verbosity
853 --version/-V: show version
854
856 distrobox-rm --name container-name [--force]
857 distrobox-rm container-name [-f]
858 You can also use environment variables to specify container manager and
860 name:
861 DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-rm
863 Supported environment variables:
865 DBX_CONTAINER_MANAGER
867 DBX_CONTAINER_NAME
868 DBX_NON_INTERACTIVE
869 DBX_SUDO_PROGRAM
870DISTROBOX-STOP(1) User Manual DISTROBOX-STOP(1)
874
878 distrobox stop
879 distrobox-stop
880
882 distrobox-stop stop a running distrobox.
883 Distroboxes are left running, even after exiting out of them, so that
885 subsequent enters are really quick. This is how they can be stopped.
886
888 distrobox stop
889 --name/-n: name for the distrobox
891 --yes/-Y: non-interactive, stop without asking
892 --help/-h: show this message
893 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
894 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
895 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
896 --verbose/-v: show more verbosity
897 --version/-V: show version
898
900 distrobox-stop --name container-name
901 distrobox-stop container-name
902 You can also use environment variables to specify container manager and
904 name:
905 DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-stop
907 Supported environment variables:
909 DBX_CONTAINER_MANAGER
911 DBX_CONTAINER_NAME
912 DBX_NON_INTERACTIVE
913 DBX_SUDO_PROGRAM
914DISTROBOX-UPGRADE(1) User Manual DISTROBOX-UPGRADE(1)
918
922 distrobox-upgrade
923
925 distrobox-upgrade will enter the specified list of containers and will
926 perform an upgrade using the container’s package manager.
927
929 distrobox upgrade
930 --help/-h: show this message
932 --all/-a: perform for all distroboxes
933 --verbose/-v: show more verbosity
934 --version/-V: show version
935
937 distrobox-upgrade --all
938 distrobox-upgrade alpine-linux ubuntu22 my-distrobox123
939 distrobox upgrade CONTAINER_NAME [CONTAINER_NAME1 CONTAINER_NAME2 ...]
940Distrobox Dec 2022 DISTROBOX-UPGRADE(1)