DISTROBOX-ASSEMBLE(1)

💅 DISTROBOX-ASSEMBLE(1) — User Manual 🦋

okay bestie, welcome to the distrobox-assemble manual page. it's giving ✨bulk container management✨ and honestly? iconic. let's get into it 💖

---

✨ NAME ✨

distrobox assemble distrobox-assemble

---

🌸 DESCRIPTION 🌸

okay so distrobox-assemble is the one that handles creating or destroying containers in batches, and it does all of that based on a manifest file. no cap, it's a whole vibe.

the manifest file, by default, is ./distrobox.ini — but bestie you can totally point it somewhere else with the --file flag. 🫶

---

🎀 SYNOPSIS 🎀

distrobox assemble

and here are the flags that ride along with it, one by one:

• --file — path or URL to the distrobox manifest/ini file 🗂️
• --name/-n — run against a single entry in the manifest/ini file 👑
• --replace/-R — replace already existing distroboxes with matching names 🔁
• --dry-run/-d — only print the container manager command generated 👀
• --verbose/-v — show more verbosity 📢
• --version/-V — show version ⭐

---

🦋 EXAMPLES 🦋

here's an example manifest file that creates two containers, because why make one when you can make two 💅

[ubuntu]
additional_packages="git vim tmux nodejs"
image=ubuntu:latest
init=false
nvidia=false
pull=true
root=false
replace=true
start_now=false

# You can add comments using this #
[arch] # also inline comments are supported
additional_packages="git vim tmux nodejs"
home=/tmp/home
image=archlinux:latest
init=false
start_now=true
init_hooks="touch /init-normal"
nvidia=true
pre_init_hooks="touch /pre-init"
pull=true
root=false
replace=false
volume="/tmp/test:/run/a /tmp/test:/run/b"

---

🌈 Create 🌈

we can bring them up simply using

distrobox assemble create

if the file is called distrobox.ini and it's in the same directory you're launching the command from, no further arguments are needed. that's the dream fr fr 😌

you can specify a custom path for the file using

distrobox assemble create --file /my/custom/path.ini

or even specify a remote file, by using an URL:

distrobox-assemble create --file https://raw.githubusercontent.com/89luca89/dotfiles/master/distrobox.ini

---

💜 Replace 💜

by default, distrobox assemble will replace a container only if replace=true is specified in the manifest file. so it's opt-in, bestie, no surprise deletions 💀

in the example of the manifest above, the ubuntu container will always be replaced when running distrobox assemble create, while the arch container will not.

to force a replace for all containers in a manifest, use the --replace flag

distrobox assemble create --replace [--file my/custom/path.ini]

---

🍓 Remove 🍓

we can bring down all the containers in a manifest file by simply doing

distrobox assemble rm

or using a custom path for the ini file

distrobox assemble rm --file my/custom/path.ini

---

🧚 Test 🧚

you can always test what distrobox would do by using the --dry-run flag. this command will only print what commands distrobox would do without actually running them. it's the rehearsal, not the performance ✨

---

💀 Clone 💀

Disclaimer: You need to start the container once to ensure it is fully initialized and created before cloning it. The container being copied must also be stopped before the cloning process can proceed.

so yeah — start it, stop it, then clone it. that's the whole ritual 🙈

---

👑 Available options 👑

this is a list of available options with the corresponding type:

🌟 Types legend: 🌟

• bool: true or false
• string: a single string, for example home="/home/luca-linux/dbox"
• string_list: multiple strings, for example additional_packages="htop vim git". Note that string_list can be declared multiple times to be compounded:

[ubuntu]
image=ubuntu:latest
additional_packages="git vim tmux nodejs"
additional_packages="htop iftop iotop"
additional_packages="zsh fish"

---

now the actual option roster, no cap, every single one:

• additional_flags (string_list) — Additional flags to pass to the container manager 🔧
• additional_packages (string_list) — Additional packages to install inside the container 📦
• home (string) — Which home directory should the container use 🏠
• hostname (string) — Set hostname of the container 🏷️
• image (string) — Which image should the container use, look here for a list 🖼️
• clone (string) — Name of the Distrobox container to use as the base for a new container (the container must be stopped). 🧬
• include (string) — Name of the entry in the manifest to include in the current definition. 🪄
• init_hooks (string_list) — Commands to run inside the container, after the packages setup 🪝
• pre_init_hooks (string_list) — Commands to run inside the container, before the packages setup 🪝
• volume (string_list) — Additional volumes to mount inside the containers 💾
• exported_apps (string_list) — App names or desktopfile paths to export 🚀
• exported_bins (string_list) — Binaries to export 🚀
• exported_bins_path (string) — Optional path where to export binaries (default: $HOME/.local/bin) 📁
• entry (bool) — Generate an entry for the container in the app list (default: false) 📝
• start_now (bool) — Start the container immediately (default: false) ⏱️
• init (bool) — Specify if this is an initful container (default: false) 🌱
• nvidia (bool) — Specify if you want to enable NVidia drivers integration (default: false) 🎮
• pull (bool) — Specify if you want to pull the image every time (default: false) ⬇️
• root (bool) — Specify if the container is rootful (default: false) 👑
• unshare_groups (bool) — Specify if the container should unshare users additional groups (default: false) 🫥
• unshare_ipc (bool) — Specify if the container should unshare the ipc namespace (default: false) 🫥
• unshare_netns (bool) — Specify if the container should unshare the network namespace (default: false) 🫥
• unshare_process (bool) — Specify if the container should unshare the process (pid) namespace (default: false) 🫥
• unshare_devsys (bool) — Specify if the container should unshare /dev (default: false) 🫥
• unshare_all (bool) — Specify if the container should unshare all the previous options (default: false) 🫥

---

the include option copies the attributes of a definition into another one. Recursive inclusions are allowed. it operates on the manifest file and the consequent distrobox containers have no relation of any kind. please be aware that attributes in the including definition will not override nor shadow the ones in the included definition, they will simply duplicate. 🪞

for further explanation of each of the other options in the list, take a look at the distrobox create usage, each option corresponds to one of the create flags. iykyk 🔥

---

⭐ Advanced example ⭐

okay bestie</p> picking right back up where we left off, no re-intro, we're just in it now 💅

this next block is the big one — a whole tumbleweed_distrobox setup that stacks a bunch of additional_packages fields, fires off a pile of init_hooks (all those go install lines and the ln -sf /usr/bin/distrobox-host-exec ... symlinks), and exports htop plus some exported_bins. copy it exactly, do not be cute with it:

[tumbleweed_distrobox]
image=registry.opensuse.org/opensuse/distrobox
pull=true
additional_packages="acpi bash-completion findutils iproute iputils sensors inotify-tools unzip"
additional_packages="net-tools nmap openssl procps psmisc rsync man tig tmux tree vim htop xclip yt-dlp"
additional_packages="git git-credential-libsecret"
additional_packages="patterns-devel-base-devel_basis"
additional_packages="ShellCheck ansible-lint clang clang-tools codespell ctags desktop-file-utils gcc golang jq python3"
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"
additional_packages="kubernetes-client helm"
init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest;
init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install github.com/onsi/ginkgo/v2/ginkgo@latest;
init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install golang.org/x/tools/cmd/goimports@latest;
init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install golang.org/x/tools/gopls@latest;
init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install sigs.k8s.io/kind@latest;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/conmon;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/crun;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/docker;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/docker-compose;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/flatpak;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/podman;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/xdg-open;
exported_apps="htop"
exported_bins="/usr/bin/htop /usr/bin/git"
exported_bins_path="~/.local/bin"

like, the range on this one?? go tooling and container tooling and a symlink farm, all in one lil config. iconic. 👑

---

✨ Clone example ✨

here's where you define one box and then just clone it into siblings — deno_ubuntu and bun_ubuntu both ride on [ubuntu] via clone=ubuntu, and each one brings its own pre_init_hooks (one curls the deno installer, one curls the bun installer). no cap:

[ubuntu]
additional_packages="git vim tmux"
image=ubuntu:latest
init=false
nvidia=false
pull=true
root=false
replace=true
start_now=true

[deno_ubuntu]
clone=ubuntu
init=false
nvidia=false
pull=true
root=false
replace=true
start_now=true
pre_init_hooks=curl -fsSL https://deno.land/install.sh | sh;

[bun_ubuntu]
clone=ubuntu
init=false
nvidia=false
pull=true
root=false
replace=true
start_now=true
pre_init_hooks=curl -fsSL https://bun.sh/install | bash;

✨ Custom login shell example ✨

want a specific login shell? you set it up in pre_init_hooks, and here it's exporting SHELL=/bin/bash; — that's the whole vibe:

[ubuntu]
image=ubuntu:latest
pre_init_hooks="export SHELL=/bin/bash;"

✨ Include example (inherit fields from another distrobox) ✨

and this is the include one — [ubuntu-nvidia] doesn't redefine everything, it just says include=ubuntu and flips nvidia=true. chef's kiss inheritance 🫶:

[ubuntu]
image=ubuntu:latest
additional_packages="git vim tmux nodejs"
additional_packages="htop iftop iotop"
additional_packages="zsh fish"

[ubuntu-nvidia]
include=ubuntu
nvidia=true

---

and that's the whole page, bestie!! 🎀 this manual came to you from the Distrobox project, dated Mar 2026 — go build yourself a lil container zoo and slay 💖✨🦋