1DISTROBOX-CREATE(1) User Manual DISTROBOX-CREATE(1)
2
6 distrobox-create takes care of creating the container with input name
7 and image. The created container will be tightly integrated with the
8 host, allowing sharing of the HOME directory of the user, external
9 storage, external usb devices and graphical apps (X11/Wayland), and au‐
10 dio.
11 Usage:
13 distrobox create --image alpine:latest --name test --init-hooks "touch /var/tmp/test1 && touch /var/tmp/test2"
15 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR-value"
16 distrobox create --image fedora:35 --name test --volume /opt/my-dir:/usr/local/my-dir:rw --additional-flags "--pids-limit -1"
17 distrobox create -i docker.io/almalinux/8-init --init --name test --pre-init-hooks "dnf config-manager --enable powertools && dnf -y install epel-release"
18 distrobox create --clone fedora-35 --name fedora-35-copy
19 distrobox create --image alpine my-alpine-container
20 distrobox create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
21 distrobox create --pull --image centos:stream9 --home ~/distrobox/centos9
22 You can also use environment variables to specify container name, image
24 and container manager:
25 DBX_CONTAINER_MANAGER="docker" DBX_NON_INTERACTIVE=1 DBX_CONTAINER_NAME=test-alpine DBX_CONTAINER_IMAGE=alpine distrobox-create
27 Supported environment variables:
29 DBX_CONTAINER_ALWAYS_PULL
31 DBX_CONTAINER_CUSTOM_HOME
32 DBX_CONTAINER_IMAGE
33 DBX_CONTAINER_MANAGER
34 DBX_CONTAINER_NAME
35 DBX_NON_INTERACTIVE
36 Options:
38 --image/-i: image to use for the container default: registry.fedoraproject.org/fedora-toolbox:36
40 --name/-n: name for the distrobox default: my-distrobox
41 --pull/-p: pull latest image unconditionally without asking
42 --yes/-Y: non-interactive, pull images without asking
43 --root/-r: launch podman/docker with root privileges. Note that if you need root this is the preferred
44 way over "sudo distrobox"
45 --clone/-c: name of the distrobox container to use as base for a new container
46 this will be useful to either rename an existing distrobox or have multiple copies
47 of the same environment.
48 --home/-H select a custom HOME directory for the container. Useful to avoid host's home littering with temp files.
49 --volume additional volumes to add to the container
50 --additional-flags/-a: additional flags to pass to the container manager command
51 --init-hooks additional commands to execute during container initialization
52 --pre-init-hooks additional commands to execute prior to container initialization
53 --init/-I use init system (like systemd) inside the container.
54 this will make host's processes not visible from within the container.
55 --help/-h: show this message
56 --dry-run/-d: only print the container manager command generated
57 --verbose/-v: show more verbosity
58 --version/-V: show version
59 Compatibility:
61 for a list of compatible images and container managers, please consult the man page:
63 man distrobox
64 man distrobox-compatibility
65 or consult the documentation page on: https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros
66 The --additional-flags or -a is useful to modify defaults in the con‐
68 tainer creations. For example:
69 distrobox create -i docker.io/library/archlinux -n dev-arch
71 podman container inspect dev-arch | jq '.[0].HostConfig.PidsLimit'
73 2048
74 distrobox rm -f dev-arch
76 distrobox create -i docker.io/library/archlinux -n dev-arch --volume $CBL_TC:/tc --additional-flags "--pids-limit -1"
77 podman container inspect dev-arch | jq '.[0].HostConfig,.PidsLimit'
79 0
80 Additional volumes can be specified using the --volume flag. This flag
82 follows the same standard as docker and podman to specify the mount
83 point so --volume SOURCE_PATH:DEST_PATH:MODE.
84 distrobox create --image docker.io/library/archlinux --name dev-arch --volume /usr/share/:/var/test:ro
86 During container creation, it is possible to specify (using the addi‐
88 tional-flags) some environment variables that will persist in the con‐
89 tainer and be independent from your environment:
90 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR-value"
92 The --init-hooks is useful to add commands to the entrypoint (init) of
94 the container. This could be useful to create containers with a set of
95 programs already installed, add users, groups.
96 distrobox create --image fedora:35 --name test --init-hooks "dnf groupinstall -y \"C Development Tools and Libraries\""
98 The --init is useful to create a container that will use its own sepa‐
100 rate init system within. For example using:
101 distrobox create -i docker.io/almalinux/8-init --init-hooks "dnf install -y openssh-server" --init --name test
103 Inside the container we will be able to use normal systemd units:
105 ~$ distrobox enter test
107 user@test:~$ sudo systemctl enable --now sshd
108 user@test:~$ sudo systemctl status sshd
109 ● sshd.service - OpenSSH server daemon
110 Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)
111 Active: active (running) since Fri 2022-01-28 22:54:50 CET; 17s ago
112 Docs: man:sshd(8)
113 man:sshd_config(5)
114 Main PID: 291 (sshd)
115 Note that enabling --init will disable host’s process integration.
117 From within the container you will not be able to see and manage host’s
118 processes. This is needed because /sbin/init must be pid 1.
119Distrobox Jun 2022 DISTROBOX-CREATE(1)