DISTROBOX-CREATE(1)

💖 DISTROBOX-CREATE — the distrobox-create glow-up guide ✨

okay bestie, welcome to the DISTROBOX-CREATE(1) manual page, aka User Manual territory, and honestly? this one is a whole serve. it's the distrobox create / distrobox-create command, and it is literally the moment your container is born. let's get into it 🎀

---

✨ NAME ✨

distrobox create distrobox-create

bestie it's giving "two names, one icon". same command, two ways to call it. 💅

---

🌸 DESCRIPTION 🌸

so distrobox-create is the one that takes care of creating the container — you feed it an input name and an image, and it does the thing. no cap.

and the container it makes? oh she's ✨integrated✨. we're talking:

• sharing of the HOME directory of the user 🏠
• external storage 💾
• external usb devices 🔌
• graphical apps — that's X11/Wayland, both of them, we don't pick favorites 🖼️
• and audio 🔊

it's the tightest host-and-guest friendship you've ever seen, fr fr. 🫶

---

🦋 SYNOPSIS 🦋

distrobox create

and now, the flags, the whole squad, in order, no skips, no shortcuts:

• --image/-i — the image to use for the container. default: ${container_image_default} 🖼️
• --name/-n — the name for the distrobox. default: ${container_name_default} 📛
• --hostname — the hostname for the distrobox. default: <container-name>.$(uname -n) 🏷️
• --pull/-p — pull the image even if it exists locally (this implies --yes, so bestie, heads up, it's gonna stop asking) 📥
• --yes/-Y — non-interactive mode, pulls images without asking 🫡
• --root/-r — launch podman/docker/lilipod with root privileges. note that if you need root, this is the preferred way over "sudo distrobox" (and also note: if using a program other than 'sudo' for root privileges is necessary, specify it through the DBX_SUDO_PROGRAM env variable, or 'distrobox_sudo_program' config variable) 👑
• --clone/-c — name of the distrobox container to use as base for a new container. this is useful to either rename an existing distrobox or have multiple copies of the same environment 🧬
• --home/-H — select a custom HOME directory for the container. useful to avoid host's home littering with temp files 🏡
• --volume — additional volumes to add to the container 📦
• --additional-flags/-a — additional flags to pass to the container manager command 🚩
• --additional-packages/-ap — additional packages to install during initial container setup 📚
• --init-hooks — additional commands to execute at the end of container initialization 🪝
• --pre-init-hooks — additional commands to execute at the start of container initialization 🪝
• --init/-I — use an init system (like systemd) inside the container. this will make host's processes not visible from within the container (it assumes --unshare-process). it may require additional packages depending on the container image: https://github.com/89luca89/distrobox/blob/main/docs/useful_tips.md#using-init-system-inside-a-distrobox ⚙️
• --nvidia — try to integrate host's nVidia drivers in the guest 🎮
• --platform — specify which platform to use, eg: linux/arm64 🧩
• --unshare-devsys — do not share host devices and sysfs dirs from host 🚫
• --unshare-groups — do not forward user's additional groups into the container 🚫
• --unshare-ipc — do not share ipc namespace with host 🚫
• --unshare-netns — do not share the net namespace with host 🚫
• --unshare-process — do not share process namespace with host 🚫
• --unshare-all — activate all the unshare flags below 🚫✨
• --compatibility/-C — show list of compatible images 📋
• --help/-h — show this message 🙋
• --no-entry — do not generate a container entry in the application list 🙈
• --dry-run/-d — only print the container manager command generated 🧪
• --verbose/-v — show more verbosity 🗣️
• --version/-V — show version 🔢
• --absolutely-disable-root-password-i-am-really-positively-sure — ⚠️ ⚠️ when setting up a rootful distrobox, this will skip user password setup, leaving it blank. ⚠️ ⚠️ 💀

bestie that last one has the longest flag name in the game for a REASON. it is loud on purpose. read it twice. leaving a password blank is not a vibe, it's a liability. 😭

---

🌈 COMPATIBILITY 🌈

for a list of compatible images and container managers, please consult the man page:

man distrobox
man distrobox-compatibility

or consult the documentation page on: https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros 🌐

---

🎀 EXAMPLES 🎀

✨ Create a distrobox with image alpine, called my-alpine container

distrobox create --image alpine my-alpine-container

✨ Create a distrobox from fedora-toolbox:35 image

distrobox create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35

✨ Clone an existing distrobox container

distrobox create --clone fedora-35 --name fedora-35-copy

✨ Always pull for the new image when creating a distrobox

distrobox create --pull --image centos:stream9 --home ~/distrobox/centos9

✨ Add additional environment variables to the container

distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR=value"

✨ Add additional volumes to the container

distrobox create --image fedora:35 --name test --volume /opt/my-dir:/usr/local/my-dir:rw --additional-flags "--pids-limit -1"

✨ Add additional packages to the container

distrobox create --image alpine:latest --name test2 --additional-packages "git tmux vim"

✨ Use init-hooks to perform an action during container startup

distrobox create --image alpine:latest --name test --init-hooks "touch /var/tmp/test1 && touch /var/tmp/test2"

✨ Use pre-init-hooks to perform an action at the beginning of the container startup (before any package manager starts)

distrobox create -i docker.io/almalinux/8-init --init --name test --pre-init-hooks "dnf config-manager --enable powertools && dnf -y install epel-release"

✨ Use init to create a Systemd container (acts similar to an LXC):

distrobox create -i ubuntu:latest --name test --additional-packages "systemd libpam-systemd pipewire-audio-client-libraries" --init

✨ Use init to create a OpenRC container (acts similar to an LXC):

distrobox create -i alpine:latest --name test --additional-packages "openrc" --init

✨ Use host's NVidia drivers integration

distrobox create --image ubuntu:22.04 --name ubuntu-nvidia --nvidia

✨ Do not use host's IP inside the container:

distrobox create --image ubuntu:latest --name test --unshare-netns

✨ Create a more isolated container, where only the $HOME, basic sockets and host's FS (in /run/host) is shared:

distrobox create --name unshared-test --unshare-all

✨ Create a more isolated container, with it's own init system, this will act very similar to a full LXC container:

distrobox create --name unshared-init-test --unshare-all --init --image fedora:latest

✨ Use environment variables to specify container name, image and container manager:

DBX_CONTAINER_MANAGER="docker" DBX_NON_INTERACTIVE=1 DBX_CONTAINER_NAME=test-alpine DBX_CONTAINER_IMAGE=alpine distrobox-create

---

🧚 ENVIRONMENT VARIABLES 🧚

the whole env var lineup, every single one, present and accounted for:

• DBX_CONTAINER_ALWAYS_PULL
• DBX_CONTAINER_CUSTOM_HOME
• DBX_CONTAINER_HOME_PREFIX
• DBX_CONTAINER_IMAGE
• DBX_CONTAINER_MANAGER
• DBX_CONTAINER_NAME
• DBX_CONTAINER_HOSTNAME
• DBX_NON_INTERACTIVE
• DBX_SUDO_PROGRAM

DBX_CONTAINER_HOME_PREFIX defines where containers' home directories will be located. If you define it as ~/dbx then all future containers' home directories will be ~/dbx/$container_name 🏠✨

✨ EXTRA ✨

okay bestie, this is the part where we get fancy 💅 these are the little extras that make your container go from "fine" to "obsessed".

---

🎀 tweaking the defaults

The --additional-flags (or -a, same thing, pick your fave) is your little remote control for the container creation defaults. like, watch this:

distrobox create -i docker.io/library/archlinux -n dev-arch

podman container inspect dev-arch | jq '.[0].HostConfig.PidsLimit'
2048

distrobox rm -f dev-arch
distrobox create -i docker.io/library/archlinux -n dev-arch --volume $CBL_TC:/tc --additional-flags "--pids-limit -1"

podman container inspect dev-arch | jq '.[0].HostConfig,.PidsLimit'
0

see how the PidsLimit went from 2048 to 0?? that's the flag doing its thing, no cap 🔥

---

🌸 adding volumes

More volumes? say less. Use the --volume flag — it follows the exact same standard as docker and podman for specifying the mount point, so it's --volume SOURCE_PATH:DEST_PATH:MODE. iconic.

distrobox create --image docker.io/library/archlinux --name dev-arch --volume /usr/share/:/var/test:ro

---

🦋 env vars that STICK

During container creation you can specify (using the additional-flags, remember her) some environment variables that will persist in the container and stay completely independent from your environment. main character energy fr fr:

distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR=value"

---

💜 --init-hooks my beloved

The --init-hooks is useful to add commands to the entrypoint (init) of the container. super handy for making containers with a whole set of programs already installed, or adding users, groups — all that setup stuff you'd otherwise do by hand 🙈

distrobox create  --image fedora:35 --name test --init-hooks "dnf groupinstall -y \"C Development Tools and Libraries\""

---

👑 --init = system container szn

The --init is useful to create a container that will use its own separate init system within. for example using:

distrobox create -i docker.io/almalinux/8-init --init --name test
distrobox create -i docker.io/library/debian --additional-packages "systemd" --init --name test-debian

Inside the container we will be able to use normal systemd units, bestie:

~$ distrobox enter test
user@test:~$ sudo systemctl enable --now sshd
user@test:~$ sudo systemctl status sshd
    ● sshd.service - OpenSSH server daemon
       Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)
       Active: active (running) since Fri 2022-01-28 22:54:50 CET; 17s ago
         Docs: man:sshd(8)
               man:sshd_config(5)
     Main PID: 291 (sshd)

⚠️ heads up bestie: enabling --init will disable host's process integration. From within the container you will not be able to see and manage host's processes. This is needed because /sbin/init must be pid 1. like, it's a whole thing, but it's required, no negotiating 💀

---

If you want to use a non-pre-create image, you'll need to add the additional package:

distrobox create -i alpine:latest --init --additional-packages "openrc" -n test
distrobox create -i debian:stable --init --additional-packages "systemd libpam-systemd pipewire-audio-client-libraries" -n test
distrobox create -i ubuntu:22.04 --init --additional-packages "systemd libpam-systemd pipewire-audio-client-libraries" -n test
distrobox create -i archlinux:latest --init --additional-packages "systemd" -n test
distrobox create -i registry.opensuse.org/opensuse/tumbleweed:latest --init --additional-packages "systemd" -n test
distrobox create -i registry.fedoraproject.org/fedora:39 --init --additional-packages "systemd" -n test

The --init flag is useful to create system containers, where the container acts more similar to a full VM than an application-container. Inside you'll have a separate init, user-session, daemons and so on. it's giving whole little computer 🌈

---

🍓 --home

The --home flag let's you specify a custom HOME for the container. Note that this will NOT prevent the mount of the host's home directory, but will ensure that configs and dotfiles will not litter it. polite of it honestly 🫶

---

💅 --root

The --root flag will let you create a container with real root privileges. At first enter the user will be required to setup a password. This is done in order to not enable passwordless sudo/su, in a rootful container — this is needed because in this mode, root inside the container is also root outside the container! 😭 like that's not a vibe, that's a whole security situation.

---

🙈 --absolutely-disable-root-password-i-am-really-positively-sure

This one will skip user password setup, leaving it blank.

🚨 This is genuinely dangerous and you really, positively should NOT enable this. I'm not playing, bestie. don't. 🛑

---

⭐ apps list moment

From version 1.4.0 of distrobox, when you create a new container, it will also generate an entry in the applications list. free app icon, we love to see it 👑

---

🦋 NVidia integration 🦋

If your host has an NVidia gpu, with installed proprietary drivers, you can integrate them with the guests by using the --nvidia flag:

distrobox create --nvidia --image ubuntu:latest --name ubuntu-nvidia

Be aware that this is not compatible with non-glibc systems and needs somewhat newer distributions to work.

This feature was tested working on:

• Almalinux
• Archlinux
• Centos 7 and newer
• Clearlinux
• Debian 10 and newer
• OpenSUSE Leap
• OpenSUSE Tumbleweed
• Rockylinux
• Ubuntu 18.04 and newer
• Void Linux (glibc)

---

and that's the whole page, bestie!! go make some containers, slay, hydrate, and remember: read the flags before you send them 💖✨

that was Distrobox, DISTROBOX-CREATE(1), dated Mar 2026 — love you, bye 🎀🦋💜