1DISTROBOX-CREATE(1) User Manual DISTROBOX-CREATE(1)
2
6 distrobox create
7 distrobox-create
8
10 distrobox-create takes care of creating the container with input name
11 and image. The created container will be tightly integrated with the
12 host, allowing sharing of the HOME directory of the user, external
13 storage, external usb devices and graphical apps (X11/Wayland), and au‐
14 dio.
15
17 distrobox create
18 --image/-i: image to use for the container default: ${container_image_default}
20 --name/-n: name for the distrobox default: ${container_name_default}
21 --pull/-p: pull the image even if it exists locally (implies --yes)
22 --yes/-Y: non-interactive, pull images without asking
23 --root/-r: launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
24 way over "sudo distrobox" (note: if using a program other than 'sudo' for root privileges is necessary,
25 specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable)
26 --clone/-c: name of the distrobox container to use as base for a new container
27 this will be useful to either rename an existing distrobox or have multiple copies
28 of the same environment.
29 --home/-H: select a custom HOME directory for the container. Useful to avoid host's home littering with temp files.
30 --volume: additional volumes to add to the container
31 --additional-flags/-a: additional flags to pass to the container manager command
32 --additional-packages/-ap: additional packages to install during initial container setup
33 --init-hooks: additional commands to execute during container initialization
34 --pre-init-hooks: additional commands to execute prior to container initialization
35 --init/-I: use init system (like systemd) inside the container.
36 this will make host's processes not visible from within the container. (assumes --unshare-process)
37 --nvidia: try to integrate host's nVidia drivers in the guest
38 --unshare-devsys: do not share host devices and sysfs dirs from host
39 --unshare-ipc: do not share ipc namespace with host
40 --unshare-netns: do not share the net namespace with host
41 --unshare-process: do not share process namespace with host
42 --unshare-all: activate all the unshare flags below
43 --compatibility/-C: show list of compatible images
44 --help/-h: show this message
45 --no-entry: do not generate a container entry in the application list
46 --dry-run/-d: only print the container manager command generated
47 --verbose/-v: show more verbosity
48 --version/-V: show version
49 --absolutely-disable-root-password-i-am-really-positively-sure: ⚠️ ⚠️ when setting up a rootful distrobox, this will skip user password setup, leaving it blank. ⚠️ ⚠️
51
53 for a list of compatible images and container managers, please consult the man page:
54 man distrobox
55 man distrobox-compatibility
56 or consult the documentation page on: https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros
57
59 Create a distrobox with image alpine, called my-alpine container
60 distrobox create --image alpine my-alpine-container
62 Create a distrobox from fedora-toolbox:35 image
64 distrobox create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
66 Clone an existing distrobox container
68 distrobox create --clone fedora-35 --name fedora-35-copy
70 Always pull for the new image when creating a distrobox
72 distrobox create --pull --image centos:stream9 --home ~/distrobox/centos9
74 Add additional environment variables to the container
76 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR=value"
78 Add additional volumes to the container
80 distrobox create --image fedora:35 --name test --volume /opt/my-dir:/usr/local/my-dir:rw --additional-flags "--pids-limit -1"
82 Add additional packages to the container
84 distrobox create --image alpine:latest --name test2 --additional-packages "git tmux vim"
86 Use init-hooks to perform an action during container startup
88 distrobox create --image alpine:latest --name test --init-hooks "touch /var/tmp/test1 && touch /var/tmp/test2"
90 Use pre-init-hooks to perform an action at the beginning of the con‐
92 tainer startup (before any package manager starts)
93 distrobox create -i docker.io/almalinux/8-init --init --name test --pre-init-hooks "dnf config-manager --enable powertools && dnf -y install epel-release"
95 Use init to create a Systemd container (acts similar to an LXC):
97 distrobox create -i ubuntu:latest --name test --additional-packages "systemd libpam-systemd" --init
99 Use init to create a OpenRC container (acts similar to an LXC):
101 distrobox create -i alpine:latest --name test --additional-packages "openrc" --init
103 Use host’s NVidia drivers integration
105 distrobox create --image ubuntu:22.04 --name ubuntu-nvidia --nvidia
107 Do not use host’s IP inside the container:
109 distrobox create --image ubuntu:latest --name test --unshare-netns
111 Create a more isolated container, where only the $HOME, basic sockets
113 and host’s FS (in /run/host) is shared:
114 distrobox create --name unshared-test --unshare-all
116 Create a more isolated container, with it’s own init system, this will
118 act very similar to a full LXC container:
119 distrobox create --name unshared-init-test --unshare-all --init --image fedora:latest
121 Use environment variables to specify container name, image and contain‐
123 er manager:
124 DBX_CONTAINER_MANAGER="docker" DBX_NON_INTERACTIVE=1 DBX_CONTAINER_NAME=test-alpine DBX_CONTAINER_IMAGE=alpine distrobox-create
126
128 DBX_CONTAINER_ALWAYS_PULL
129 DBX_CONTAINER_CUSTOM_HOME
130 DBX_CONTAINER_HOME_PREFIX
131 DBX_CONTAINER_IMAGE
132 DBX_CONTAINER_MANAGER
133 DBX_CONTAINER_NAME
134 DBX_NON_INTERACTIVE
135 DBX_SUDO_PROGRAM
136 DBX_CONTAINER_HOME_PREFIX defines where containers’ home directories
138 will be located. If you define it as ~/dbx then all future containers’
139 home directories will be ~/dbx/$container_name
140
142 The --additional-flags or -a is useful to modify defaults in the con‐
143 tainer creations. For example:
144 distrobox create -i docker.io/library/archlinux -n dev-arch
146 podman container inspect dev-arch | jq '.[0].HostConfig.PidsLimit'
148 2048
149 distrobox rm -f dev-arch
151 distrobox create -i docker.io/library/archlinux -n dev-arch --volume $CBL_TC:/tc --additional-flags "--pids-limit -1"
152 podman container inspect dev-arch | jq '.[0].HostConfig,.PidsLimit'
154 0
155 Additional volumes can be specified using the --volume flag. This flag
157 follows the same standard as docker and podman to specify the mount
158 point so --volume SOURCE_PATH:DEST_PATH:MODE.
159 distrobox create --image docker.io/library/archlinux --name dev-arch --volume /usr/share/:/var/test:ro
161 During container creation, it is possible to specify (using the addi‐
163 tional-flags) some environment variables that will persist in the con‐
164 tainer and be independent from your environment:
165 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR=value"
167 The --init-hooks is useful to add commands to the entrypoint (init) of
169 the container. This could be useful to create containers with a set of
170 programs already installed, add users, groups.
171 distrobox create --image fedora:35 --name test --init-hooks "dnf groupinstall -y \"C Development Tools and Libraries\""
173 The --init is useful to create a container that will use its own sepa‐
175 rate init system within. For example using:
176 distrobox create -i docker.io/almalinux/8-init --init --name test
178 distrobox create -i docker.io/library/debian --additional-packages "systemd" --init --name test-debian
179 Inside the container we will be able to use normal systemd units:
181 ~$ distrobox enter test
183 user@test:~$ sudo systemctl enable --now sshd
184 user@test:~$ sudo systemctl status sshd
185 ● sshd.service - OpenSSH server daemon
186 Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)
187 Active: active (running) since Fri 2022-01-28 22:54:50 CET; 17s ago
188 Docs: man:sshd(8)
189 man:sshd_config(5)
190 Main PID: 291 (sshd)
191 Note that enabling --init will disable host’s process integration.
193 From within the container you will not be able to see and manage host’s
194 processes. This is needed because /sbin/init must be pid 1.
195 If you want to use a non-pre-create image, you’ll need to add the addi‐
197 tional package:
198 distrobox create -i alpine:latest --init --additional-packages "openrc" -n test
200 distrobox create -i debian:stable --init --additional-packages "systemd libpam-systemd" -n test
201 distrobox create -i ubuntu:22.04 --init --additional-packages "systemd libpam-systemd" -n test
202 distrobox create -i archlinux:latest --init --additional-packages "systemd" -n test
203 distrobox create -i registry.opensuse.org/opensuse/tumbleweed:latest --init --additional-packages "systemd" -n test
204 distrobox create -i registry.fedoraproject.org/fedora:38 --init --additional-packages "systemd" -n test
205 The --init flag is useful to create system containers, where the con‐
207 tainer acts more similar to a full VM than an application-container.
208 Inside you’ll have a separate init, user-session, daemons and so on.
209 The --home flag let’s you specify a custom HOME for the container.
211 Note that this will NOT prevent the mount of the host’s home directory,
212 but will ensure that configs and dotfiles will not litter it.
213 The --root flag will let you create a container with real root privi‐
215 leges. At first enter the user will be required to setup a password.
216 This is done in order to not enable passwordless sudo/su, in a rootful
217 container, this is needed because in this mode, root inside the con‐
218 tainer is also root outside the container!
219 The --absolutely-disable-root-password-i-am-really-positively-sure will
221 skip user password setup, leaving it blank. This is genuinely danger‐
222 ous and you really, positively should NOT enable this.
223 From version 1.4.0 of distrobox, when you create a new container, it
225 will also generate an entry in the applications list.
226 NVidia integration
228 If your host has an NVidia gpu, with installed proprietary drivers, you
229 can integrate them with the guests by using the --nvidia flag:
230 distrobox create --nvidia --image ubuntu:latest --name ubuntu-nvidia
232 Be aware that this is not compatible with non-glibc systems and needs
234 somewhat newer distributions to work.
235 This feature was tested working on:
237 • Almalinux
239 • Archlinux
241 • Centos 7 and newer
243 • Clearlinux
245 • Debian 10 and newer
247 • OpenSUSE Leap
249 • OpenSUSE Tumbleweed
251 • Rockylinux
253 • Ubuntu 18.04 and newer
255 • Void Linux (glibc)
257Distrobox Nov 2023 DISTROBOX-CREATE(1)