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: registry.fedoraproject.org/fedora-toolbox:36
20 --name/-n: name for the distrobox default: my-distrobox
21 --pull/-p: pull latest image unconditionally without asking
22 --yes/-Y: non-interactive, pull images without asking
23 --root/-r: launch podman/docker 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 --init-hooks additional commands to execute during container initialization
33 --pre-init-hooks additional commands to execute prior to container initialization
34 --init/-I use init system (like systemd) inside the container.
35 this will make host's processes not visible from within the container.
36 --compatibility/-C: show list of compatible images
37 --help/-h: show this message
38 --no-entry: do not generate a container entry in the application list
39 --dry-run/-d: only print the container manager command generated
40 --verbose/-v: show more verbosity
41 --version/-V: show version
42
44 for a list of compatible images and container managers, please consult the man page:
45 man distrobox
46 man distrobox-compatibility
47 or consult the documentation page on: https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros
48
50 distrobox create --image alpine:latest --name test --init-hooks "touch /var/tmp/test1 && touch /var/tmp/test2"
51 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR-value"
52 distrobox create --image fedora:35 --name test --volume /opt/my-dir:/usr/local/my-dir:rw --additional-flags "--pids-limit -1"
53 distrobox create -i docker.io/almalinux/8-init --init --name test --pre-init-hooks "dnf config-manager --enable powertools && dnf -y install epel-release"
54 distrobox create --clone fedora-35 --name fedora-35-copy
55 distrobox create --image alpine my-alpine-container
56 distrobox create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
57 distrobox create --pull --image centos:stream9 --home ~/distrobox/centos9
58 You can also use environment variables to specify container name, image
60 and container manager:
61 DBX_CONTAINER_MANAGER="docker" DBX_NON_INTERACTIVE=1 DBX_CONTAINER_NAME=test-alpine DBX_CONTAINER_IMAGE=alpine distrobox-create
63 Supported environment variables:
65 DBX_CONTAINER_ALWAYS_PULL
67 DBX_CONTAINER_CUSTOM_HOME
68 DBX_CONTAINER_HOME_PREFIX
69 DBX_CONTAINER_IMAGE
70 DBX_CONTAINER_MANAGER
71 DBX_CONTAINER_NAME
72 DBX_NON_INTERACTIVE
73 DBX_SUDO_PROGRAM
74 DBX_CONTAINER_HOME_PREFIX defines where containers’ home directories
76 will be located. If you define it as ~/dbx then all future containers’
77 home directories will be ~/dbx/$container_name
78 The --additional-flags or -a is useful to modify defaults in the con‐
80 tainer creations. For example:
81 distrobox create -i docker.io/library/archlinux -n dev-arch
83 podman container inspect dev-arch | jq '.[0].HostConfig.PidsLimit'
85 2048
86 distrobox rm -f dev-arch
88 distrobox create -i docker.io/library/archlinux -n dev-arch --volume $CBL_TC:/tc --additional-flags "--pids-limit -1"
89 podman container inspect dev-arch | jq '.[0].HostConfig,.PidsLimit'
91 0
92 Additional volumes can be specified using the --volume flag. This flag
94 follows the same standard as docker and podman to specify the mount
95 point so --volume SOURCE_PATH:DEST_PATH:MODE.
96 distrobox create --image docker.io/library/archlinux --name dev-arch --volume /usr/share/:/var/test:ro
98 During container creation, it is possible to specify (using the addi‐
100 tional-flags) some environment variables that will persist in the con‐
101 tainer and be independent from your environment:
102 distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR-value"
104 The --init-hooks is useful to add commands to the entrypoint (init) of
106 the container. This could be useful to create containers with a set of
107 programs already installed, add users, groups.
108 distrobox create --image fedora:35 --name test --init-hooks "dnf groupinstall -y \"C Development Tools and Libraries\""
110 The --init is useful to create a container that will use its own sepa‐
112 rate init system within. For example using:
113 distrobox create -i docker.io/almalinux/8-init --init-hooks "dnf install -y openssh-server" --init --name test
115 Inside the container we will be able to use normal systemd units:
117 ~$ distrobox enter test
119 user@test:~$ sudo systemctl enable --now sshd
120 user@test:~$ sudo systemctl status sshd
121 ● sshd.service - OpenSSH server daemon
122 Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)
123 Active: active (running) since Fri 2022-01-28 22:54:50 CET; 17s ago
124 Docs: man:sshd(8)
125 man:sshd_config(5)
126 Main PID: 291 (sshd)
127 Note that enabling --init will disable host’s process integration.
129 From within the container you will not be able to see and manage host’s
130 processes. This is needed because /sbin/init must be pid 1.
131 The --home flag let’s you specify a custom HOME for the container.
133 Note that this will NOT prevent the mount of the host’s home directory,
134 but will ensure that configs and dotfiles will not litter it.
135 From version 1.4.0 of distrobox, when you create a new container, it
137 will also generate an entry in the applications list.
138Distrobox Dec 2022 DISTROBOX-CREATE(1)