1DISTROBOX-ASSEMBLE(1) User Manual DISTROBOX-ASSEMBLE(1)
2
6 distrobox assemble
7 distrobox-assemble
8
10 distrobox-assemble takes care of creating or destroying containers in
11 batches, based on a manifest file. The manifest file by default is
12 ./distrobox.ini, but can be specified using the --file flag.
13
15 distrobox assemble
16 --file: path to the distrobox manifest/ini file
18 --name/-n: run against a single entry in the manifest/ini file
19 --replace/-R: replace already existing distroboxes with matching names
20 --dry-run/-d: only print the container manager command generated
21 --verbose/-v: show more verbosity
22 --version/-V: show version
23
25 This is an example manifest file to create two containers:
26 [ubuntu]
28 additional_packages="git vim tmux nodejs"
29 image=ubuntu:latest
30 init=false
31 nvidia=false
32 pull=true
33 root=false
34 replace=true
35 start_now=false
36 # You can add comments using this #
38 [arch] # also inline comments are supported
39 additional_packages="git vim tmux nodejs"
40 home=/tmp/home
41 image=archlinux:latest
42 init=false
43 start_now=true
44 init_hooks="touch /init-normal"
45 nvidia=true
46 pre_init_hooks="touch /pre-init"
47 pull=true
48 root=false
49 replace=false
50 volume="/tmp/test:/run/a /tmp/test:/run/b"
51 Create
53 We can bring them up simply using
55 distrobox assemble create
57 If the file is called distrobox.ini and is in the same directory you’re
59 launching the command, no further arguments are needed. You can speci‐
60 fy a custom path for the file using
61 distrobox assemble create --file /my/custom/path.ini
63 Replace
65 By default, distrobox assemble will replace a container only if re‐
67 place=true is specified in the manifest file.
68 In the example of the manifest above, the ubuntu container will always
70 be replaced when running distrobox assemble create, while the arch con‐
71 tainer will not.
72 To force a replace for all containers in a manifest use the --replace
74 flag
75 distrobox assemble create --replace [--file my/custom/path.ini]
77 Remove
79 We can bring down all the containers in a manifest file by simply doing
81 distrobox assemble rm
83 Or using a custom path for the ini file
85 distrobox assemble rm --file my/custom/path.ini
87 Test
89 You can always test what distrobox would do by using the --dry-run
91 flag. This command will only print what commands distrobox would do
92 without actually running them.
93 Available options
95 This is a list of available options with the corresponding type:
97 Flag Name Type
99 ─────────────────────────────
100 additional_flags string
101 additional_packages string
102 home string
103 image string
104 init_hooks string
105 pre_init_hooks string
106 volume string
107 exported_apps string
108 exported_bins string
109 exported_bins_path string
110 entry bool
111 start_now bool
112 init bool
113 nvidia bool
114 pull bool
115 root bool
116 unshare_ipc bool
117 unshare_netns bool
118 unshare_process bool
119 unshare_devsys bool
120 unshare_all bool
121 boolean options default to false if not specified. string options can
123 be broken in multiple declarations additively in order to improve read‐
124 ability of the file:
125 [ubuntu]
127 image=ubuntu:latest
128 additional_packages="git vim tmux nodejs"
129 additional_packages="htop iftop iotop"
130 additional_packages="zsh fish"
131 Be aware that if you’re doing lines with spaces, you need to quote
133 them. If you’re doing multiple hooks (init or pre_init) in multiple
134 lines, end the line with a semicolon (;) in order to execute them one
135 after the other.
136 For an explanation of each of the option in the list, take a look at
138 the distrobox create usage, each option corresponds to one of the cre‐
139 ate flags.
140 Advanced example
142 [tumbleweed_distrobox]
144 image=registry.opensuse.org/opensuse/distrobox
145 pull=true
146 additional_packages="acpi bash-completion findutils iproute iputils sensors inotify-tools unzip"
147 additional_packages="net-tools nmap openssl procps psmisc rsync man tig tmux tree vim htop xclip yt-dlp"
148 additional_packages="git git-credential-libsecret"
149 additional_packages="patterns-devel-base-devel_basis"
150 additional_packages="ShellCheck ansible-lint clang clang-tools codespell ctags desktop-file-utils gcc golang jq python3"
151 additional_packages="python3-bashate python3-flake8 python3-mypy python3-pipx python3-pycodestyle python3-pyflakes python3-pylint python3-python-lsp-server python3-rstcheck python3-yapf python3-yamllint rustup shfmt"
152 additional_packages="kubernetes-client helm"
153 init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest;
154 init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install github.com/onsi/ginkgo/v2/ginkgo@latest;
155 init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install golang.org/x/tools/cmd/goimports@latest;
156 init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install golang.org/x/tools/gopls@latest;
157 init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install sigs.k8s.io/kind@latest;
158 init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/conmon;
159 init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/crun;
160 init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/docker;
161 init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/docker-compose;
162 init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/flatpak;
163 init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/podman;
164 init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/xdg-open;
165 exported_apps="htop"
166 exported_bins="/usr/bin/htop /usr/bin/git"
167 exported_bins_path="~/.local/bin"
168DISTROBOX(1) User Manual DISTROBOX(1)
172
176 This project does not need a dedicated image. It can use any OCI im‐
177 ages from docker-hub, quay.io, or any registry of your choice.
178 Many cloud images are stripped down on purpose to save size and may not
180 include commands such as which, mount, less or vi). Additional pack‐
181 ages can be installed once inside the container. We recommend using
182 your preferred automation tool inside the container if you find your‐
183 self having to repeatedly create new containers. Maintaining your own
184 custom image is also an option.
185 The main concern is having basic Linux utilities (mount), basic user
187 management utilities (usermod, passwd), and sudo correctly set.
188 SUPPORTED CONTAINER MANAGERS
190 distrobox can run on either podman, docker or lilipod
191 (https://github.com/89luca89/lilipod)
192 It depends either on podman configured in rootless mode or on docker
194 configured without sudo (follow THESE instructions (https://docs.dock‐
195 er.com/engine/install/linux-postinstall/))
196 • Minimum podman version: 2.1.0
198 • Minimum docker client version: 19.03.15
200 • Minimum lilipod version: v0.0.1
202 Follow the official installation guide here:
204 • <https://podman.io/getting-started/installation>
206 • <https://docs.docker.com/engine/install>
208 • <https://docs.docker.com/engine/install/linux-postinstall/>
210 CONTAINERS DISTROS
212 Distrobox guests tested successfully with the following container im‐
213 ages:
214 Distro Version Images
216 ──────────────────────────────────────────────────────────────────────────────
217 AlmaLinux (Toolbox) 8 9 quay.io/toolbx-im‐
218 ages/almalinux-tool‐
219 box:8 quay.io/toolbx-
220 images/almalinux-tool‐
221 box:9 quay.io/toolbx-
222 images/almalinux-tool‐
223 box:latest
224 Alpine (Toolbox) 3.16 3.17 3.18 edge quay.io/toolbx-im‐
225 ages/alpine-tool‐
226 box:3.16 quay.io/tool‐
227 bx-images/alpine-tool‐
228 box:3.17 quay.io/tool‐
229 bx-images/alpine-tool‐
230 box:3.18 quay.io/tool‐
231 bx-images/alpine-tool‐
232 box:edge quay.io/tool‐
233 bx-images/alpine-tool‐
234 box:latest
235 AmazonLinux (Toolbox) 2 2022 quay.io/toolbx-im‐
236 ages/amazonlinux-tool‐
237 box:2 quay.io/toolbx-
238 images/amazonlinux-
239 toolbox:2023
240 quay.io/toolbx-im‐
241 ages/amazonlinux-tool‐
242 box:latest
243 Archlinux (Toolbox) quay.io/toolbx-im‐
244 ages/archlinux-tool‐
245 box:latest
246 Bazzite Arch ghcr.io/ublue-os/bazz‐
247 ite-arch:latest
248 ghcr.io/ublue-os/bazz‐
249 ite-arch-gnome:latest
250 Centos (Toolbox) stream8 stream9 quay.io/toolbx-im‐
251 ages/centos-tool‐
252 box:stream8
253 quay.io/toolbx-im‐
254 ages/centos-tool‐
255 box:stream9
256 quay.io/toolbx-im‐
257 ages/centos-tool‐
258 box:latest
259 Debian (Toolbox) 10 11 12 testing unsta‐ quay.io/toolbx-im‐
266 ble ages/debian-toolbox:10
267 quay.io/toolbx-im‐
268 ages/debian-toolbox:11
269 quay.io/toolbx-im‐
270 ages/debian-toolbox:12
271 quay.io/toolbx-im‐
272 ages/debian-tool‐
273 box:testing
274 quay.io/toolbx-im‐
275 ages/debian-toolbox:un‐
276 stable quay.io/toolbx-
277 images/debian-tool‐
278 box:latest
279 Fedora (Toolbox) 36 37 38 39 Rawhide registry.fedorapro‐
280 ject.org/fedora-tool‐
281 box:37 registry.fedo‐
282 raproject.org/fedora-
283 toolbox:38 registry.fe‐
284 doraproject.org/fedora-
285 toolbox:39 registry.fe‐
286 doraproject.org/fedora-
287 toolbox:latest
288 openSUSE (Toolbox) registry.open‐
289 suse.org/opensuse/dis‐
290 trobox:latest
291 quay.io/toolbx-im‐
292 ages/opensuse-tool‐
293 box:tumbleweed
294 quay.io/toolbx-im‐
295 ages/opensuse-tool‐
296 box:latest
297 RedHat (Toolbox) 8 9 registry.access.red‐
298 hat.com/ubi8/toolbox
299 registry.access.red‐
300 hat.com/ubi9/toolbox
301 quay.io/toolbx-im‐
302 ages/rhel-toolbox:lat‐
303 est
304 Rocky Linux (Toolbox) 8 9 quay.io/toolbx-im‐
305 ages/rockylinux-tool‐
306 box:8 quay.io/toolbx-
307 images/rockylinux-tool‐
308 box:9 quay.io/toolbx-
309 images/rockylinux-tool‐
310 box:latest
311 Ubuntu (Toolbox) 16.04 18.04 20.04 22.04 quay.io/toolbx-im‐
312 ages/ubuntu-tool‐
313 box:16.04 quay.io/tool‐
314 bx-images/ubuntu-tool‐
315 box:18.04 quay.io/tool‐
316 bx-images/ubuntu-tool‐
317 box:20.04 quay.io/tool‐
318 bx-images/ubuntu-tool‐
319 box:22.04 quay.io/tool‐
320 bx-images/ubuntu-tool‐
321 box:latest
322 AlmaLinux (UBI) 8 quay.io/almalin‐
324 ux/8-base:8 quay.io/al‐
325 malinux/8-init:8
326 AlmaLinux 8 8-minimal 9 9-minimal quay.io/almalinux/alma‐
332 linux:8 quay.io/almal‐
333 inux/almalinux:9
334 quay.io/almalinux/alma‐
335 linux:9-minimal
336 Alpine Linux 3.15 3.16 docker.io/li‐
337 brary/alpine:3.15 dock‐
338 er.io/li‐
339 brary/alpine:3.16 dock‐
340 er.io/li‐
341 brary/alpine:latest
342 AmazonLinux 1 2 2023 public.ecr.aws/amazon‐
343 linux/amazonlinux:1
344 public.ecr.aws/amazon‐
345 linux/amazonlinux:2
346 public.ecr.aws/amazon‐
347 linux/amazonlinux:2023
348 Archlinux docker.io/library/arch‐
349 linux:latest
350 CentOS Stream 8 9 quay.io/centos/cen‐
351 tos:stream8
352 quay.io/centos/cen‐
353 tos:stream9
354 CentOS 7 quay.io/centos/centos:7
355 Chainguard Wolfi Small note: sudo is cgr.dev/chain‐
356 missing, use su-exec guard/wolfi-base:latest
357 instead.
358 ClearLinux docker.io/li‐
359 brary/clearlinux:latest
360 docker.io/li‐
361 brary/clearlinux:base
362 Crystal Linux reg‐
363 istry.getcryst.al/crys‐
364 tal/misc/docker:latest
365 Debian 7 8 9 10 11 12 docker.io/de‐
366 bian/eol:wheezy dock‐
367 er.io/library/de‐
368 bian:buster-backports
369 docker.io/library/de‐
370 bian:bullseye-backports
371 docker.io/library/de‐
372 bian:bookworm-backports
373 docker.io/library/de‐
374 bian:stable-backports
375 Debian Testing docker.io/library/de‐
376 bian:testing dock‐
377 er.io/library/de‐
378 bian:testing-backports
379 Debian Unstable docker.io/library/de‐
380 bian:unstable
381 deepin 20 (apricot) 23 (beige) docker.io/lin‐
382 uxdeepin/apricot dock‐
383 er.io/linuxdeepin/beige
384 Fedora 36 37 38 39 Rawhide quay.io/fedora/fedo‐
385 ra:36 registry.fedo‐
386 raproject.org/fedora:37
387 quay.io/fedora/fedo‐
388 ra:38 quay.io/fedo‐
389 ra/fedora:39
390 Gentoo Linux rolling docker.io/gen‐
391 too/stage3:latest
392 KDE neon Latest Testing Unstable invent-reg‐
398 istry.kde.org/neon/dock‐
399 er-images/plasma:latest
400 invent-reg‐
401 istry.kde.org/neon/dock‐
402 er-images/plasma:test‐
403 ing invent-reg‐
404 istry.kde.org/neon/dock‐
405 er-images/plasma:unsta‐
406 ble
407 Kali Linux rolling docker.io/kalilin‐
408 ux/kali-rolling:latest
409 Mint 21.1 docker.io/lin‐
410 uxmintd/mint21.1-amd64
411 Neurodebian nd100 docker.io/library/neu‐
412 rodebian:nd100
413 openSUSE Leap registry.open‐
414 suse.org/open‐
415 suse/leap:latest
416 openSUSE Tumbleweed registry.open‐
417 suse.org/opensuse/dis‐
418 trobox:latest reg‐
419 istry.opensuse.org/open‐
420 suse/tumbleweed:latest
421 registry.open‐
422 suse.org/opensuse/tool‐
423 box:latest
424 Oracle Linux 7 7-slim 8 8-slim 9 container-registry.ora‐
425 9-slim cle.com/os/oraclelinux:7
426 container-registry.ora‐
427 cle.com/os/oraclelin‐
428 ux:7-slim container-reg‐
429 istry.oracle.com/os/ora‐
430 clelinux:8 container-
431 registry.ora‐
432 cle.com/os/oraclelin‐
433 ux:8-slim container-reg‐
434 istry.oracle.com/os/ora‐
435 clelinux:9 container-
436 registry.ora‐
437 cle.com/os/oraclelin‐
438 ux:9-slim
439 RedHat (UBI) 7 8 9 registry.access.red‐
440 hat.com/ubi7/ubi reg‐
441 istry.access.red‐
442 hat.com/ubi7/ubi-init
443 registry.access.red‐
444 hat.com/ubi8/ubi reg‐
445 istry.access.red‐
446 hat.com/ubi8/ubi-init
447 registry.access.red‐
448 hat.com/ubi8/ubi-minimal
449 registry.access.red‐
450 hat.com/ubi9/ubi reg‐
451 istry.access.red‐
452 hat.com/ubi9/ubi-init
453 registry.access.red‐
454 hat.com/ubi9/ubi-minimal
455 Rocky Linux 8 8-minimal 9 quay.io/rockylinux/rock‐
456 ylinux:8 quay.io/rock‐
457 ylinux/rockylinux:8-min‐
458 imal quay.io/rockylin‐
459 ux/rockylinux:9
460 quay.io/rockylinux/rock‐
461 ylinux:latest
462 Scientific Linux 7 docker.io/library/sl:7
464 Slackware 14.2 docker.io/vbatts/slack‐
465 ware:14.2
466 Ubuntu 14.04 16.04 18.04 20.04 docker.io/library/ubun‐
467 22.04 23.04 tu:14.04 docker.io/li‐
468 brary/ubuntu:16.04 dock‐
469 er.io/library/ubun‐
470 tu:18.04 docker.io/li‐
471 brary/ubuntu:20.04 dock‐
472 er.io/library/ubun‐
473 tu:22.04
474 Vanilla OS VSO ghcr.io/vanilla-
475 os/vso:main
476 Void Linux ghcr.io/void-linux/void-
477 glibc-full:latest
478 Images marked with Toolbox are tailored images made by the community
480 efforts in toolbx-images/images (https://github.com/toolbx-images/im‐
481 ages), so they are more indicated for desktop use, and first setup will
482 take less time. Note however that if you use a non-toolbox preconfig‐
483 ured image, the first distrobox-enter you’ll perform can take a while
484 as it will download and install the missing dependencies.
485 A small time tax to pay for the ability to use any type of image. This
487 will not occur after the first time, subsequent enters will be much
488 faster.
489 NixOS is not a supported container distro, and there are currently no
491 plans to bring support to it. If you are looking for unprivileged
492 NixOS environments, we suggest you look into nix-shell
493 (https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html) or
494 nix portable (https://github.com/DavHau/nix-portable)
495 NEW DISTRO SUPPORT
497 If your distro of choice is not on the list, open an issue requesting
498 support for it, we can work together to check if it is possible to add
499 support for it.
500 Or just try using it anyway, if it works, open an issue and it will be
502 added to the list!
503 OLDER DISTRIBUTIONS
505 For older distributions like CentOS 5, CentOS 6, Debian 6, Ubuntu
506 12.04, compatibility is not assured.
507 Their libc version is incompatible with kernel releases after >=4.11.
509 A work around this is to use the vsyscall=emulate flag in the bootload‐
510 er of the host.
511 Keep also in mind that mirrors could be down for such old releases, so
513 you will need to build a custom distrobox image to ensure basic depen‐
514 dencies are met.
515 GPU ACCELERATION SUPPORT
517 For Intel and AMD Gpus, the support is baked in, as the containers will
518 install their latest available mesa/dri drivers.
519 For NVidia, you can use the --nvidia flag during create, see distrobox-
521 create documentation to discover how to use it.
522 Alternatively, you can use the nvidia-container-toolkit utility to set
524 up the integration independently from the distrobox’s own flag.
525DISTROBOX-CREATE(1) User Manual DISTROBOX-CREATE(1)
529
533 distrobox create
534 distrobox-create
535
537 distrobox-create takes care of creating the container with input name
538 and image. The created container will be tightly integrated with the
539 host, allowing sharing of the HOME directory of the user, external
540 storage, external usb devices and graphical apps (X11/Wayland), and au‐
541 dio.
542
544 distrobox create
545 --image/-i: image to use for the container default: ${container_image_default}
547 --name/-n: name for the distrobox default: ${container_name_default}
548 --pull/-p: pull the image even if it exists locally (implies --yes)
549 --yes/-Y: non-interactive, pull images without asking
550 --root/-r: launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
551 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
552 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
553 --clone/-c: name of the distrobox container to use as base for a new container
554 this will be useful to either rename an existing distrobox or have multiple copies
555 of the same environment.
556 --home/-H: select a custom HOME directory for the container. Useful to avoid host's home littering with temp files.
557 --volume: additional volumes to add to the container
558 --additional-flags/-a: additional flags to pass to the container manager command
559 --additional-packages/-ap: additional packages to install during initial container setup
560 --init-hooks: additional commands to execute during container initialization
561 --pre-init-hooks: additional commands to execute prior to container initialization
562 --init/-I: use init system (like systemd) inside the container.
563 this will make host's processes not visible from within the container. (assumes --unshare-process)
564 --nvidia: try to integrate host's nVidia drivers in the guest
565 --unshare-devsys: do not share host devices and sysfs dirs from host
566 --unshare-ipc: do not share ipc namespace with host
567 --unshare-netns: do not share the net namespace with host
568 --unshare-process: do not share process namespace with host
569 --unshare-all: activate all the unshare flags below
570 --compatibility/-C: show list of compatible images
571 --help/-h: show this message
572 --no-entry: do not generate a container entry in the application list
573 --dry-run/-d: only print the container manager command generated
574 --verbose/-v: show more verbosity
575 --version/-V: show version
576 --absolutely-disable-root-password-i-am-really-positively-sure: ⚠️ ⚠️ when setting up a rootful distrobox, this will skip user password setup, leaving it blank. ⚠️ ⚠️
578
580 for a list of compatible images and container managers, please consult the man page:
581 man distrobox
582 man distrobox-compatibility
583 or consult the documentation page on: https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros
584
586 Create a distrobox with image alpine, called my-alpine container
587 distrobox create --image alpine my-alpine-container
589 Create a distrobox from fedora-toolbox:35 image
591 distrobox create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
593 Clone an existing distrobox container
595 distrobox create --clone fedora-35 --name fedora-35-copy
597 Always pull for the new image when creating a distrobox
599 distrobox create --pull --image centos:stream9 --home ~/distrobox/centos9
601 Add additional environment variables to the container
603 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR=value"
605 Add additional volumes to the container
607 distrobox create --image fedora:35 --name test --volume /opt/my-dir:/usr/local/my-dir:rw --additional-flags "--pids-limit -1"
609 Add additional packages to the container
611 distrobox create --image alpine:latest --name test2 --additional-packages "git tmux vim"
613 Use init-hooks to perform an action during container startup
615 distrobox create --image alpine:latest --name test --init-hooks "touch /var/tmp/test1 && touch /var/tmp/test2"
617 Use pre-init-hooks to perform an action at the beginning of the con‐
619 tainer startup (before any package manager starts)
620 distrobox create -i docker.io/almalinux/8-init --init --name test --pre-init-hooks "dnf config-manager --enable powertools && dnf -y install epel-release"
622 Use init to create a Systemd container (acts similar to an LXC):
624 distrobox create -i ubuntu:latest --name test --additional-packages "systemd libpam-systemd" --init
626 Use init to create a OpenRC container (acts similar to an LXC):
628 distrobox create -i alpine:latest --name test --additional-packages "openrc" --init
630 Use host’s NVidia drivers integration
632 distrobox create --image ubuntu:22.04 --name ubuntu-nvidia --nvidia
634 Do not use host’s IP inside the container:
636 distrobox create --image ubuntu:latest --name test --unshare-netns
638 Create a more isolated container, where only the $HOME, basic sockets
640 and host’s FS (in /run/host) is shared:
641 distrobox create --name unshared-test --unshare-all
643 Create a more isolated container, with it’s own init system, this will
645 act very similar to a full LXC container:
646 distrobox create --name unshared-init-test --unshare-all --init --image fedora:latest
648 Use environment variables to specify container name, image and contain‐
650 er manager:
651 DBX_CONTAINER_MANAGER="docker" DBX_NON_INTERACTIVE=1 DBX_CONTAINER_NAME=test-alpine DBX_CONTAINER_IMAGE=alpine distrobox-create
653
655 DBX_CONTAINER_ALWAYS_PULL
656 DBX_CONTAINER_CUSTOM_HOME
657 DBX_CONTAINER_HOME_PREFIX
658 DBX_CONTAINER_IMAGE
659 DBX_CONTAINER_MANAGER
660 DBX_CONTAINER_NAME
661 DBX_NON_INTERACTIVE
662 DBX_SUDO_PROGRAM
663 DBX_CONTAINER_HOME_PREFIX defines where containers’ home directories
665 will be located. If you define it as ~/dbx then all future containers’
666 home directories will be ~/dbx/$container_name
667
669 The --additional-flags or -a is useful to modify defaults in the con‐
670 tainer creations. For example:
671 distrobox create -i docker.io/library/archlinux -n dev-arch
673 podman container inspect dev-arch | jq '.[0].HostConfig.PidsLimit'
675 2048
676 distrobox rm -f dev-arch
678 distrobox create -i docker.io/library/archlinux -n dev-arch --volume $CBL_TC:/tc --additional-flags "--pids-limit -1"
679 podman container inspect dev-arch | jq '.[0].HostConfig,.PidsLimit'
681 0
682 Additional volumes can be specified using the --volume flag. This flag
684 follows the same standard as docker and podman to specify the mount
685 point so --volume SOURCE_PATH:DEST_PATH:MODE.
686 distrobox create --image docker.io/library/archlinux --name dev-arch --volume /usr/share/:/var/test:ro
688 During container creation, it is possible to specify (using the addi‐
690 tional-flags) some environment variables that will persist in the con‐
691 tainer and be independent from your environment:
692 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR=value"
694 The --init-hooks is useful to add commands to the entrypoint (init) of
696 the container. This could be useful to create containers with a set of
697 programs already installed, add users, groups.
698 distrobox create --image fedora:35 --name test --init-hooks "dnf groupinstall -y \"C Development Tools and Libraries\""
700 The --init is useful to create a container that will use its own sepa‐
702 rate init system within. For example using:
703 distrobox create -i docker.io/almalinux/8-init --init --name test
705 distrobox create -i docker.io/library/debian --additional-packages "systemd" --init --name test-debian
706 Inside the container we will be able to use normal systemd units:
708 ~$ distrobox enter test
710 user@test:~$ sudo systemctl enable --now sshd
711 user@test:~$ sudo systemctl status sshd
712 ● sshd.service - OpenSSH server daemon
713 Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)
714 Active: active (running) since Fri 2022-01-28 22:54:50 CET; 17s ago
715 Docs: man:sshd(8)
716 man:sshd_config(5)
717 Main PID: 291 (sshd)
718 Note that enabling --init will disable host’s process integration.
720 From within the container you will not be able to see and manage host’s
721 processes. This is needed because /sbin/init must be pid 1.
722 If you want to use a non-pre-create image, you’ll need to add the addi‐
724 tional package:
725 distrobox create -i alpine:latest --init --additional-packages "openrc" -n test
727 distrobox create -i debian:stable --init --additional-packages "systemd libpam-systemd" -n test
728 distrobox create -i ubuntu:22.04 --init --additional-packages "systemd libpam-systemd" -n test
729 distrobox create -i archlinux:latest --init --additional-packages "systemd" -n test
730 distrobox create -i registry.opensuse.org/opensuse/tumbleweed:latest --init --additional-packages "systemd" -n test
731 distrobox create -i registry.fedoraproject.org/fedora:38 --init --additional-packages "systemd" -n test
732 The --init flag is useful to create system containers, where the con‐
734 tainer acts more similar to a full VM than an application-container.
735 Inside you’ll have a separate init, user-session, daemons and so on.
736 The --home flag let’s you specify a custom HOME for the container.
738 Note that this will NOT prevent the mount of the host’s home directory,
739 but will ensure that configs and dotfiles will not litter it.
740 The --root flag will let you create a container with real root privi‐
742 leges. At first enter the user will be required to setup a password.
743 This is done in order to not enable passwordless sudo/su, in a rootful
744 container, this is needed because in this mode, root inside the con‐
745 tainer is also root outside the container!
746 The --absolutely-disable-root-password-i-am-really-positively-sure will
748 skip user password setup, leaving it blank. This is genuinely danger‐
749 ous and you really, positively should NOT enable this.
750 From version 1.4.0 of distrobox, when you create a new container, it
752 will also generate an entry in the applications list.
753 NVidia integration
755 If your host has an NVidia gpu, with installed proprietary drivers, you
756 can integrate them with the guests by using the --nvidia flag:
757 distrobox create --nvidia --image ubuntu:latest --name ubuntu-nvidia
759 Be aware that this is not compatible with non-glibc systems and needs
761 somewhat newer distributions to work.
762 This feature was tested working on:
764 • Almalinux
766 • Archlinux
768 • Centos 7 and newer
770 • Clearlinux
772 • Debian 10 and newer
774 • OpenSUSE Leap
776 • OpenSUSE Tumbleweed
778 • Rockylinux
780 • Ubuntu 18.04 and newer
782 • Void Linux (glibc)
784DISTROBOX-ENTER(1) User Manual DISTROBOX-ENTER(1)
788
792 distrobox enter
793 distrobox-enter
794
796 distrobox-enter takes care of entering the container with the name
797 specified. Default command executed is your SHELL, but you can specify
798 different shells or entire commands to execute. If using it inside a
799 script, an application, or a service, you can specify the –headless
800 mode to disable tty and interactivity.
801
803 distrobox enter
804 --name/-n: name for the distrobox default: my-distrobox
806 --/-e: end arguments execute the rest as command to execute at login default: bash -l
807 --no-tty/-T: do not instantiate a tty
808 --no-workdir/-nw: always start the container from container's home directory
809 --additional-flags/-a: additional flags to pass to the container manager command
810 --help/-h: show this message
811 --root/-r: launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
812 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
813 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
814 --dry-run/-d: only print the container manager command generated
815 --verbose/-v: show more verbosity
816 --version/-V: show version
817
819 Enter a distrobox named “example”
820 distrobox-enter example
822 Enter a distrobox specifying a command
824 distrobox-enter --name fedora-toolbox-35 -- bash -l
826 distrobox-enter my-alpine-container -- sh -l
827 Use additional podman/docker/lilipod flags while entering a distrobox
829 distrobox-enter --additional-flags "--preserve-fds" --name test -- bash -l
831 Specify additional environment variables while entering a distrobox
833 distrobox-enter --additional-flags "--env MY_VAR=value" --name test -- bash -l
835 MY_VAR=value distrobox-enter --additional-flags "--preserve-fds" --name test -- bash -l
836 You can also use environment variables to specify container manager and
838 container name:
839 DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-enter
841
843 DBX_CONTAINER_NAME
844 DBX_CONTAINER_MANAGER
845 DBX_SKIP_WORKDIR
846 DBX_SUDO_PROGRAM
847
849 This command is used to enter the distrobox itself. Personally, I just
850 create multiple profiles in my gnome-terminal to have multiple distros
851 accessible.
852 The --additional-flags or -a is useful to modify default command when
854 executing in the container. For example:
855 distrobox enter -n dev-arch --additional-flags "--env my_var=test" -- printenv &| grep my_var
857 my_var=test
858 This is possible also using normal env variables:
860 my_var=test distrobox enter -n dev-arch --additional-flags -- printenv &| grep my_var
862 my_var=test
863 If you’d like to enter a rootful container having distrobox use a pro‐
865 gram other than `sudo' to run podman/docker/lilipod as root, such as
866 `pkexec' or `doas', you may specify it with the DBX_SUDO_PROGRAM envi‐
867 ronment variable. For example, to use `doas' to enter a rootful con‐
868 tainer:
869 DBX_SUDO_PROGRAM="doas" distrobox enter -n container --root
871 Additionally, in one of the config file paths that distrobox supports,
873 such as ~/.distroboxrc, you can also append the line distrobox_su‐
874 do_program="doas" (for example) to always run distrobox commands in‐
875 volving rootful containers using `doas'.
876DISTROBOX-EPHEMERAL(1) User Manual DISTROBOX-EPHEMERAL(1)
880
884 distrobox ephemeral
885 distrobox-ephemeral
886
888 distrobox-ephemeral creates a temporary distrobox that is automatically
889 destroyed when the command is terminated.
890
892 distrobox ephemeral
893 --root/-r: launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
895 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
896 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
897 --verbose/-v: show more verbosity
898 --help/-h: show this message
899 --/-e: end arguments execute the rest as command to execute at login default: bash -l
900 --version/-V: show version
901
903 distrobox-ephemeral --image alpine:latest -- cat /etc/os-release
904 distrobox-ephemeral --root --verbose --image alpine:latest --volume /opt:/opt
905 You can also use flags from distrobox-create to customize the ephemeral
907 container to run.
908
910 distrobox-create --help
911 man distrobox-create
912
914 distrobox-ephemeral calls distrobox-create, SEE ALSO distrobox-create(1) for
915 a list of supported environment variables to use.
916DISTROBOX-EXPORT(1) User Manual DISTROBOX-EXPORT(1)
920
924 distrobox-export
925
927 Application and binary exporting
928 distrobox-export takes care of exporting an app or a binary from the
930 container to the host.
931 The exported app will be easily available in your normal launcher and
933 it will automatically be launched from the container it is exported
934 from.
935
937 distrobox-export
938 --app/-a: name of the application to export
940 --bin/-b: absolute path of the binary to export
941 --delete/-d: delete exported application or binary
942 --export-label/-el: label to add to exported application name.
943 Use "none" to disable.
944 Defaults to (on \$container_name)
945 --export-path/-ep: path where to export the binary
946 --extra-flags/-ef: extra flags to add to the command
947 --sudo/-S: specify if the exported item should be run as sudo
948 --help/-h: show this message
949 --verbose/-v: show more verbosity
950 --version/-V: show version
951 You may want to install graphical applications or CLI tools in your
953 distrobox. Using distrobox-export from inside the container will let
954 you use them from the host itself.
955
957 distrobox-export --app mpv [--extra-flags "flags"] [--delete] [--sudo]
958 distrobox-export --bin /path/to/bin [--export-path ~/.local/bin] [--extra-flags "flags"] [--delete] [--sudo]
959 App export example
961 distrobox-export --app abiword
963 This tool will simply copy the original .desktop files along with need‐
965 ed icons, add the prefix /usr/local/bin/distrobox-enter -n dis‐
966 trobox_name -e ... to the commands to run, and save them in your home
967 to be used directly from the host as a normal app.
968 Binary export example
970 distrobox-export --bin /usr/bin/code --extra-flags "--foreground" --export-path $HOME/.local/bin
972 In the case of exporting binaries, you will have to specify where to
974 export it (--export-path) and the tool will create a little wrapper
975 script that will distrobox-enter -e from the host, the desired binary.
976 This can be handy with the use of direnv to have different versions of
977 the same binary based on your env or project.
978 The exported binaries will be exported in the “–export-path” of choice
980 as a wrapper script that acts naturally both on the host and in the
981 container.
982 Additional flags
984 You can specify additional flags to add to the command, for example if
986 you want to export an electron app, you could add the “–foreground”
987 flag to the command:
988 distrobox-export --app atom --extra-flags "--foreground"
990 distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --extra-flags "-p"
991 This works for binaries and apps. Extra flags are only used then the
993 exported app or binary is used from the host, using them inside the
994 container will not include them.
995 Unexport
997 The option “–delete” will un-export an app or binary
999 distrobox-export --app atom --delete
1001 distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --delete
1002 Run as root in the container
1004 The option “–sudo” will launch the exported item as root inside the
1006 distrobox.
1007 Exporting apps from rootful containers
1009 It is worth noting that, when exporting any item - which includes
1011 graphical apps - from rootful containers (created with distrobox create
1012 --root), root privileges will be needed every time the item is launched
1013 (in order to enter the rootful container), which, by default, is done
1014 using sudo (see docs for distrobox-enter on how to customize that).
1015 However, for graphical apps in specific, since they launch without a
1016 terminal, the usage of sudo might, at first, make it impossible to
1017 launch them.
1018 To fix this without needing to customize the sudo program, one can de‐
1020 fine a global SUDO_ASKPASS environment variable on their machine, which
1021 is a PATH to an executable that is run by sudo when no terminal is
1022 available (or when it is given the --askpass or -A option), and the
1023 output of that executable to stdout is used as the password input. The
1024 executable is called as many times is needed for authentication as root
1025 to succeed (unless a limit of amount of attempts is reached).
1026 To do this, pick a program to ask the user for graphical password in‐
1028 put. In this example, we will use zenity --password, which should be
1029 present for GNOME users (and can also be installed in other DEs) -
1030 there are other options, such as kdialog --password "Message" for KDE
1031 users.
1032 Write the call to the desired program to a script file, for example to
1034 /usr/bin/my-password-prompt (sample contents below):
1035 #!/bin/sh
1037 zenity --password "Authentication as root is required"
1038 (You may save the script under, for example, ~/.local/bin if you want
1040 to keep it fully local to your user.)
1041 Afterwards, make it executable (e.g. run sudo chmod +x /usr/bin/my-
1043 password-prompt). Then, make sure to set SUDO_ASKPASS to "/usr/bin/my-
1044 password-prompt" (replace with your script’s path) in a global profile
1045 file, so that it is picked up by sudo when running graphical apps (and,
1046 therefore, sudo will run the script you created to ask for a password).
1047 This is done with the shell line export SU‐
1048 DO_ASKPASS="/path/to/script/goes/here". You can do this for your user
1049 only by running the command below (replace the script path as needed):
1050 echo 'export SUDO_ASKPASS="/usr/bin/my-password-prompt"' >> ~/.profile
1052 Which appends the appropriate line to the end of your ~/.profile file,
1054 thus making the change local to your user. Alternatively, to set it
1055 system-wide (for all users), you may create a file in /etc/profile.d/
1056 (or equivalent for your system) with that line.
1057 Now just log out and log back in, and graphical apps exported from
1059 rootful containers should now be properly asking for root’s password
1060 before launching (instead of not opening, if that was the case before).
1061 Notes
1063 Note you can use –app OR –bin but not together.
1065 [IMAGE: app-export (https://user-images.githubusercon‐
1067 tent.com/598882/144294795-c7785620-bf68-4d1b-b251-1e1f0a32a08d.png)]
1068 NOTE: some electron apps such as vscode and atom need additional flags
1070 to work from inside the container, use the --extra-flags option to pro‐
1071 vide a series of flags, for example:
1072 distrobox-export --app atom --extra-flags "--foreground"
1074DISTROBOX-GENERATE-ENTRY(1) User Manual DISTROBOX-GENERATE-ENTRY(1)
1078
1082 distrobox generate-entry
1083
1085 distrobox-generate-entry will create a desktop icon for one of the
1086 available distroboxes. This will be then deleted when you remove the
1087 matching distrobox.
1088
1090 distrobox generate-entry
1091 --help/-h: show this message
1093 --all/-a: perform for all distroboxes
1094 --delete/-d: delete the entry
1095 --icon/-i: specify a custom icon [/path/to/icon] (default auto)
1096 --root/-r: perform on rootful distroboxes
1097 --verbose/-v: show more verbosity
1098 --version/-V: show version
1099
1101 Generate an entry for a container
1102 distrobox generate-entry my-container-name
1104 Specify a custom icon for the entry
1106 distrobox generate-entry my-container-name --icon /path/to/icon.png
1108 Generate an entry for all distroboxes
1110 distrobox generate-entry --all
1112 Delete an entry
1114 distrobox generate-entry container-name --delete
1116DISTROBOX-HOST-EXEC(1) User Manual DISTROBOX-HOST-EXEC(1)
1120
1124 distrobox-host-exec
1125
1127 distrobox-host-exec lets one execute command on the host, while inside
1128 of a container.
1129 Under the hood, distrobox-host-exec uses host-spawn a project that lets
1131 us execute commands back on the host. If the tool is not found the us‐
1132 er will be prompted to install it.
1133
1135 Just pass to “distrobox-host-exec” any command and all its arguments,
1136 if any.
1137 --help/-h: show this message
1139 --verbose/-v: show more verbosity
1140 --version/-V: show version
1141 --yes/-Y: Automatically answer yes to prompt:
1142 host-spawn will be installed on the guest system
1143 if host-spawn is not detected.
1144 This behaviour is default when running in a non-interactive shell.
1145 If no command is provided, it will execute “$SHELL”.
1147 Alternatively, use symlinks to make distrobox-host-exec execute as that
1149 command:
1150 ~$: ln -s /usr/bin/distrobox-host-exec /usr/local/bin/podman
1152 ~$: ls -l /usr/local/bin/podman
1153 lrwxrwxrwx. 1 root root 51 Jul 11 19:26 /usr/local/bin/podman -> /usr/bin/distrobox-host-exec
1154 ~$: podman version
1155 ...this is executed on host...
1156
1158 distrobox-host-exec ls
1159 distrobox-host-exec bash -l
1160 distrobox-host-exec flatpak run org.mozilla.firefox
1161 distrobox-host-exec podman ps -a
1162DISTROBOX-INIT(1) User Manual DISTROBOX-INIT(1)
1166
1170 distrobox-init
1171
1173 Init the distrobox (not to be launched manually)
1174 distrobox-init is the entrypoint of a created distrobox. Note that
1176 this HAS to run from inside a distrobox, will not work if you run it
1177 from your host.
1178 This is not intended to be used manually, but instead used by dis‐
1180 trobox-create to set up the container’s entrypoint.
1181 distrobox-init will take care of installing missing dependencies (eg.
1183 sudo), set up the user and groups, mount directories from the host to
1184 ensure the tight integration.
1185
1187 distrobox-init
1188 --name/-n: user name
1190 --user/-u: uid of the user
1191 --group/-g: gid of the user
1192 --home/-d: path/to/home of the user
1193 --help/-h: show this message
1194 --additional-packages: packages to install in addition
1195 --init/-I: whether to use or not init
1196 --pre-init-hooks: commands to execute prior to init
1197 --nvidia: try to integrate host's nVidia drivers in the guest
1198 --upgrade/-U: run init in upgrade mode
1199 --verbose/-v: show more verbosity
1200 --version/-V: show version
1201 --: end arguments execute the rest as command to execute during init
1202
1204 distrobox-init --name test-user --user 1000 --group 1000 --home /home/test-user
1205 distrobox-init --upgrade
1206DISTROBOX-LIST(1) User Manual DISTROBOX-LIST(1)
1208
1212 distrobox list
1213 distrobox-list
1214
1216 distrobox-list lists available distroboxes. It detects them and lists
1217 them separately from the rest of normal containers.
1218
1220 distrobox list
1221 --help/-h: show this message
1223 --no-color: disable color formatting
1224 --root/-r: launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
1225 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
1226 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
1227 --verbose/-v: show more verbosity
1228 --version/-V: show version
1229
1231 distrobox-list
1232 You can also use environment variables to specify container manager
1234 DBX_CONTAINER_MANAGER="docker" distrobox-list
1236
1238 DBX_CONTAINER_MANAGER
1239 DBX_SUDO_PROGRAM
1240 [IMAGE: image (https://user-images.githubusercon‐
1242 tent.com/598882/147831082-24b5bc2e-b47e-49ac-9b1a-a209478c9705.png)]
1243DISTROBOX-RM(1) User Manual DISTROBOX-RM(1)
1247
1251 distrobox rm
1252 distrobox-rm
1253
1255 distrobox-rm delete one of the available distroboxes.
1256
1258 distrobox rm
1259 --all/-a: delete all distroboxes
1261 --force/-f: force deletion
1262 --rm-home: remove the mounted home if it differs from the host user's one
1263 --root/-r: launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
1264 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
1265 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
1266 --help/-h: show this message
1267 --verbose/-v: show more verbosity
1268 --version/-V: show version
1269
1271 distrobox-rm container-name [--force] [--all]
1272 You can also use environment variables to specify container manager and
1274 name:
1275 DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-rm
1277
1279 DBX_CONTAINER_MANAGER
1280 DBX_CONTAINER_NAME
1281 DBX_NON_INTERACTIVE
1282 DBX_SUDO_PROGRAM
1283DISTROBOX-STOP(1) User Manual DISTROBOX-STOP(1)
1287
1291 distrobox stop
1292 distrobox-stop
1293
1295 distrobox-stop stop a running distrobox.
1296 Distroboxes are left running, even after exiting out of them, so that
1298 subsequent enters are really quick. This is how they can be stopped.
1299
1301 distrobox stop
1302 --all/-a: stop all distroboxes
1304 --yes/-Y: non-interactive, stop without asking
1305 --help/-h: show this message
1306 --root/-r: launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
1307 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
1308 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
1309 --verbose/-v: show more verbosity
1310 --version/-V: show version
1311
1313 distrobox-stop container-name1 container-name2
1314 distrobox-stop container-name
1315 distrobox-stop --all
1316 You can also use environment variables to specify container manager and
1318 name:
1319 DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-stop
1321
1323 DBX_CONTAINER_MANAGER
1324 DBX_CONTAINER_NAME
1325 DBX_NON_INTERACTIVE
1326 DBX_SUDO_PROGRAM
1327DISTROBOX-UPGRADE(1) User Manual DISTROBOX-UPGRADE(1)
1331
1335 distrobox-upgrade
1336
1338 distrobox-upgrade will enter the specified list of containers and will
1339 perform an upgrade using the container’s package manager.
1340
1342 distrobox upgrade
1343 --help/-h: show this message
1345 --all/-a: perform for all distroboxes
1346 --running: perform only on running distroboxes
1347 --root/-r: launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
1348 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
1349 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
1350 --verbose/-v: show more verbosity
1351 --version/-V: show version
1352
1354 Upgrade all distroboxes
1355 distrobox-upgrade --all
1357 Upgrade all running distroboxes
1359 distrobox-upgrade --all --running
1361 Upgrade a specific distrobox
1363 distrobox-upgrade alpine-linux
1365 Upgrade a list of distroboxes
1367 distrobox-upgrade alpine-linux ubuntu22 my-distrobox123
1369 Automatically update all distro
1371 You can create a systemd service to perform distrobox-upgrade automati‐
1373 cally, this example shows how to run it daily:
1374 ~/.config/systemd/user/distrobox-upgrade.service
1376 [Unit]
1378 Description=distrobox-upgrade Automatic Update
1379 [Service]
1381 Type=simple
1382 ExecStart=distrobox-upgrade --all
1383 StandardOutput=null
1384 ~/.config/systemd/user/distrobox-upgrade.timer
1386 [Unit]
1388 Description=distrobox-upgrade Automatic Update Trigger
1389 [Timer]
1391 OnBootSec=1h
1392 OnUnitInactiveSec=1d
1393 [Install]
1395 WantedBy=timers.target
1396 Then simply do a systemctl --user daemon-reload && systemctl --user en‐
1398 able --now distrobox-upgrade.timer
1399Distrobox Nov 2023 DISTROBOX-UPGRADE(1)