DISTROBOX-ASSEMBLE(1)

📦

version 1.8.2.5 · 6 versions

1.8.2.5 · alpine 3.24, arch rolling, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking (latest)
1.8.0 · opensuse-leap 16.0
1.4.2.1 · debian bookworm
1.7.0 · ubuntu noble
1.8.2.4 · fedora 44, ubuntu resolute
1.8.1.2 · debian trixie, fedora 43, ubuntu questing

, in alpine 3.24, arch rolling, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 distrobox-assemble(1) — the User Manual, but make it cute 💖

okay bestie, buckle UP, because this is distrobox-assemble from the User Manual and she is that girl. 🦋

✨ NAME ✨

distrobox assemble distrobox-assemble

🌸 DESCRIPTION 🌸

okay so distrobox-assemble is literally the batch-queen of distrobox. She creates or destroys containers in batches, based on a manifest file. no cap. 📋✨

The manifest file by default is ./distrobox.ini, but you can point her at a different one with the --file flag. 💅

🎀 SYNOPSIS 🎀

distrobox assemble

--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 🧚

This is an example manifest file to create two containers, and honestly? she ate. 💅

[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 is in the same directory you're launching the command, no further arguments are needed. iconic behaviour, 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. lowkey important, bestie.

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. peek before you leap, queen. 🎀

👯 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. ✋😭

🌈 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"

👑 The big list (flag name → type → what she does)

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

              [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"

🧬 Clone example 🧬

like, you make one container and then a whole lil family of them that all start from the same DNA. clone= and everything else is just your own tweaks on top:

[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;

want your own shell to be the one that greets you when you walk in? okay, say less:

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

🫂 Include example (inherit fields from another distrobox) 🫂

include= is the "borrow your bestie's whole closet" move — you inherit every field from another distrobox entry and then override whatever you want. iconic behavior, fr fr:

[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

Distrobox                           Mar 2026              DISTROBOX-ASSEMBLE(1)
────────────────────────────────────────────────────────────────────────────────
DISTROBOX(1)                      User Manual                      DISTROBOX(1)

🌈 COMPATIBILITY 🌈

okay so this is the part where I hold your hand and tell you it's all gonna be fine 💖

This project does not need a dedicated image. It can use any OCI images from docker-hub, quay.io, or any registry of your choice. literally any of them. go wild.

Many cloud images are stripped down on purpose to save size and may not include commands such as which, mount, less or vi). Additional packages can be installed once inside the container. We recommend using your preferred automation tool inside the container if you find yourself having to repeatedly create new containers. Maintaining your own custom image is also an option.

The main concern is having basic Linux utilities (mount), basic user management utilities (usermod, passwd), and sudo correctly set.

🫶 SUPPORTED CONTAINER MANAGERS 🫶

distrobox can run on either podman, docker or lilipod

It depends either on podman configured in rootless mode or on docker configured without sudo (follow THESE instructions)

Minimum podman version: 2.1.0
Minimum docker client version: 19.03.15
Minimum lilipod version: v0.0.1

Follow the official installation guide here:

🦋 CONTAINERS DISTROS 🦋

distrobox guests tested successfully with the following container images — here's the whole roster, bestie, no gatekeeping 👑

AlmaLinux (Toolbox) — versions: 8, 9
- quay.io/toolbx-images/almalinux-toolbox:8
- quay.io/toolbx-images/almalinux-toolbox:9
- quay.io/toolbx-images/almalinux-toolbox:latest
Alpine (Toolbox) — versions: 3.20, 3.21, 3.22, edge
- quay.io/toolbx-images/alpine-toolbox:3.20
- quay.io/toolbx-images/alpine-toolbox:3.21
- quay.io/toolbx-images/alpine-toolbox:3.22
- quay.io/toolbx-images/alpine-toolbox:edge
- quay.io/toolbx-images/alpine-toolbox:latest
AmazonLinux (Toolbox) — versions: 2, 2022
- quay.io/toolbx-images/amazonlinux-toolbox:2
- quay.io/toolbx-images/amazonlinux-toolbox:2023
- quay.io/toolbx-images/amazonlinux-toolbox:latest
Archlinux (Toolbox) — no version tags listed
- quay.io/toolbx/arch-toolbox:latest
ALT Linux — versions: p10, p11, sisyphus
- docker.io/library/alt:p10
- docker.io/library/alt:p11
- docker.io/library/alt:sisyphus
Bazzite Arch — no version tags listed
- ghcr.io/ublue-os/bazzite-arch:latest
- ghcr.io/ublue-os/bazzite-arch-gnome:latest
Centos (Toolbox) — versions: stream9, stream10
- quay.io/toolbx-images/centos-toolbox:stream9
- quay.io/toolbx-images/centos-toolbox:stream10
- quay.io/toolbx-images/centos-toolbox:latest
Debian (Toolbox) — versions: 11, 12, 13, testing, unstable
- quay.io/toolbx-images/debian-toolbox:11
- quay.io/toolbx-images/debian-toolbox:12
- quay.io/toolbx-images/debian-toolbox:13
- quay.io/toolbx-images/debian-toolbox:testing
- quay.io/toolbx-images/debian-toolbox:unstable
- quay.io/toolbx-images/debian-toolbox:latest
Fedora (Toolbox) — versions: 38, 39, 40, 41, 42, 43, Rawhide
- registry.fedoraproject.org/fedora-toolbox:38
- registry.fedoraproject.org/fedora-toolbox:39
- registry.fedoraproject.org/fedora-toolbox:40
- quay.io/fedora/fedora-toolbox:41
- quay.io/fedora/fedora-toolbox:42
- quay.io/fedora/fedora-toolbox:43
- quay.io/fedora/fedora-toolbox:rawhide
openSUSE (Toolbox) — no version tags listed
- registry.opensuse.org/opensuse/distrobox:latest
RedHat (Toolbox) — versions: 8, 9
- registry.access.redhat.com/ubi8/toolbox
- registry.access.redhat.com/ubi9/toolbox
Rocky Linux (Toolbox) — versions: 8, 9
- quay.io/toolbx-images/rockylinux-toolbox:8
- quay.io/toolbx-images/rockylinux-toolbox:9
- quay.io/toolbx-images/rockylinux-toolbox:latest
Ubuntu (Toolbox) — versions: 16.04, 18.04, 20.04, 22.04, 24.04
- quay.io/toolbx/ubuntu-toolbox:16.04
- quay.io/toolbx/ubuntu-toolbox:18.04
- quay.io/toolbx/ubuntu-toolbox:20.04
- quay.io/toolbx/ubuntu-toolbox:22.04
- quay.io/toolbx/ubuntu-toolbox:24.04
- quay.io/toolbx/ubuntu-toolbox:latest
Chainguard Wolfi (Toolbox) — no version tags listed
- quay.io/toolbx-images/wolfi-toolbox:latest
Ublue — versions: ubuntu-toolbox, fedora-toolbox, wolfi-toolbox, archlinux-distrobox
- ghcr.io/ublue-os/ubuntu-toolbox
- ghcr.io/ublue-os/fedora-toolbox
- ghcr.io/ublue-os/wolfi-toolbox
- ghcr.io/ublue-os/arch-toolbox

okay so here's the whole ✨menu✨ of what you can actually spin up, bestie — every distro, every version tag, every image path, no skips, no cap 💅

AlmaLinux — versions 8, 8-minimal, 9 → docker.io/library/almalinux:8, docker.io/library/almalinux:9
Alpine Linux — versions 3.20, 3.21, 3.22, edge → docker.io/library/alpine:3.20, docker.io/library/alpine:3.21, docker.io/library/alpine:3.22, docker.io/library/alpine:edge, docker.io/library/alpine:latest
AmazonLinux — versions 1, 2, 2023 → public.ecr.aws/amazonlinux/amazonlinux:1, public.ecr.aws/amazonlinux/amazonlinux:2, public.ecr.aws/amazonlinux/amazonlinux:2023
Archlinux → docker.io/library/archlinux:latest
Blackarch → docker.io/blackarchlinux/blackarch:latest
CentOS Stream — versions 8, 9, 10 → quay.io/centos/centos:stream8, quay.io/centos/centos:stream9, quay.io/centos/centos:stream10
Chainguard Wolfi → cgr.dev/chainguard/wolfi-base:latest
Chimera Linux → docker.io/chimeralinux/chimera:latest
Crystal Linux → registry.gitlab.com/crystal-linux/misc/docker:latest
Debian — versions 7, 8, 9, 10, 11, 12, 13 → docker.io/debian/eol:wheezy, docker.io/debian/eol:buster, docker.io/debian/eol:bullseye, docker.io/library/debian:bookworm-backports, docker.io/library/debian:stable-backports
Debian — Testing → docker.io/library/debian:testing, docker.io/library/debian:testing-backports
Debian — Unstable → docker.io/library/debian:unstable
deepin — 20 (apricot), 23 (beige) → docker.io/linuxdeepin/apricot, docker.io/linuxdeepin/deepin:beige
Fedora — versions 38, 39, 40, 41, 42, 43, Rawhide → quay.io/fedora/fedora:38, quay.io/fedora/fedora:39, quay.io/fedora/fedora:40, quay.io/fedora/fedora:41, quay.io/fedora/fedora:42, quay.io/fedora/fedora:43, quay.io/fedora/fedora:rawhide
Gentoo Linux — rolling → docker.io/gentoo/stage3:latest
KDE neon — Latest → invent-registry.kde.org/neon/docker-images/plasma:latest
Kali Linux — rolling → docker.io/kalilinux/kali-rolling:latest
Mint — 22.3 → docker.io/linuxmintd/mint22.3-amd64
Neurodebian — nd120 → docker.io/library/neurodebian:nd120
openSUSE — Leap → registry.opensuse.org/opensuse/leap:latest
openSUSE — Tumbleweed → registry.opensuse.org/opensuse/distrobox:latest, registry.opensuse.org/opensuse/tumbleweed:latest, registry.opensuse.org/opensuse/toolbox:latest, registry.opensuse.org/opensuse/distrobox-bpftrace:latest
Oracle Linux — versions 8, 8-slim, 9, 9-slim, 10, 10-slim → container-registry.oracle.com/os/oraclelinux:8, container-registry.oracle.com/os/oraclelinux:8-slim, container-registry.oracle.com/os/oraclelinux:9, container-registry.oracle.com/os/oraclelinux:9-slim, container-registry.oracle.com/os/oraclelinux:10, container-registry.oracle.com/os/oraclelinux:10-slim
RedHat (UBI) — versions 7, 8, 9 → registry.access.redhat.com/ubi7/ubi, registry.access.redhat.com/ubi8/ubi, registry.access.redhat.com/ubi8/ubi-init, registry.access.redhat.com/ubi8/ubi-minimal, registry.access.redhat.com/ubi9/ubi, registry.access.redhat.com/ubi9/ubi-init, registry.access.redhat.com/ubi9/ubi-minimal
Rocky Linux — versions 8, 8-minimal, 9 → quay.io/rockylinux/rockylinux:8, quay.io/rockylinux/rockylinux:8-minimal, quay.io/rockylinux/rockylinux:9, quay.io/rockylinux/rockylinux:latest
Slackware → docker.io/vbatts/slackware:current
SteamOS → ghcr.io/linuxserver/steamos:latest
Ubuntu — versions 14.04, 16.04, 18.04, 20.04, 22.04, 24.04 → docker.io/library/ubuntu:14.04, docker.io/library/ubuntu:16.04, docker.io/library/ubuntu:18.04, docker.io/library/ubuntu:20.04, docker.io/library/ubuntu:22.04, docker.io/library/ubuntu:24.04
Vanilla OS — VSO → ghcr.io/vanilla-os/vso:main
Void Linux — glibc, musl → ghcr.io/void-linux/void-glibc-full:latest, ghcr.io/void-linux/void-musl-full:latest

Images marked with Toolbox are tailored images made by the community efforts in toolbx-images/images, so they're more indicated for desktop use, and first setup will take less time ✨ Note however that if you use a non-toolbox preconfigured image, the first distrobox-enter you'll perform can take a while as it will download and install the missing dependencies 😭

A small time tax to pay for the ability to use any type of image 💸 This will not occur after the first time, subsequent enters will be much faster 🏃‍♀️💨

NixOS is not a supported container distro, and there are currently no plans to bring support to it 💀 If you're looking for unprivileged NixOS environments, we suggest you look into nix-shell or nix portable.

🌱 NEW DISTRO SUPPORT

If your distro of choice is not on the list, open an issue requesting support for it — we can work together to check if it's possible to add support for it 🫶

Or just try using it anyway 🎀 if it works, open an issue and it will be added to the list! bestie that's literally the whole vibe

👵 OLDER DISTRIBUTIONS

For older distributions like CentOS 5, CentOS 6, Debian 6, Ubuntu 12.04, compatibility is not assured 🙈

Their libc version is incompatible with kernel releases after >=4.11 💀 A work around this is to use the vsyscall=emulate flag in the bootloader of the host 🛠️

Keep also in mind that mirrors could be down for such old releases, so you will need to build a custom distrobox image to ensure basic dependencies are met 😤

🎮 GPU ACCELERATION SUPPORT

For Intel and AMD Gpus, the support is baked in — the containers will install their latest available mesa/dri drivers 🧚

For NVidia, you can use the --nvidia flag during create, see distrobox-create documentation to discover how to use it 👑

Alternatively, you can use the nvidia-container-toolkit utility to set up the integration independently from the distrobox's own flag 💅

Distrobox                           Mar 2026                       DISTROBOX(1)
────────────────────────────────────────────────────────────────────────────────
DISTROBOX-CREATE(1)               User Manual               DISTROBOX-CREATE(1)

🎀 NAME

distrobox create distrobox-create

💫 DESCRIPTION

distrobox-create takes care of creating the container with input name and image ✨ The created container will be tightly integrated with the host, allowing sharing of the HOME directory of the user, external storage, external usb devices and graphical apps (X11/Wayland), and audio 🔊🦋

✨ SYNOPSIS ✨

distrobox create

okay bestie, buckle up, this is the big one — distrobox create has a lot of knobs and honestly every single one of them is here:

--image/-i — the image you're building the container from. default: ${container_image_default} 💖
--name/-n — what you're naming 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 already exists locally (heads up: this implies --yes) 🔥
--yes/-Y — non-interactive mode, so it'll pull images without asking you anything 🙈
--root/-r — launch podman/docker/lilipod with root privileges. real talk: if you need root, this is the preferred way over "sudo distrobox". (note: if you need a program other than 'sudo' for root privileges, specify it through the DBX_SUDO_PROGRAM env variable, or the 'distrobox_sudo_program' config variable) 👑
--clone/-c — name of the distrobox container to use as the base for a new container. this is useful to either rename an existing distrobox or have multiple copies of the same environment. ✨
--home/-H — pick a custom HOME directory for the container. super useful to avoid your host's home getting littered 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 the 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 makes the host's processes invisible from inside the container. (assumes --unshare-process) it may need 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 the host's nVidia drivers into the guest 🌈
--platform — specify which platform to use, eg: linux/arm64
--unshare-devsys — do not share host devices and sysfs dirs from the host
--unshare-groups — do not forward the user's additional groups into the container
--unshare-ipc — do not share the ipc namespace with the host
--unshare-netns — do not share the net namespace with the host
--unshare-process — do not share the process namespace with the host
--unshare-all — activate all the unshare flags below 🛡️
--compatibility/-C — show the 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 that gets 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. ⚠️ ⚠️

no cap, that last flag is named that way on purpose. the name is doing a vibe check on you. if you type it, you meant it, and you're leaving that password blank, fr fr. 😭

🌸 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 💖

okay this is the part where it all clicks. here's every example, exactly as it's meant to be typed. go off:

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

that last one is peak group-chat energy tbh — set the vars, fire the command, zero flags, immaculate. 💅✨

🌈 ENVIRONMENT VARIABLES 🌈

these are the env vars, bestie, the whole roster:

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

so yeah, one little variable and suddenly every container gets its own lil bedroom under ~/dbx. obsessed. 🫶

🌈 EXTRA 🌈

okay so bestie, the --additional-flags flag (or -a if you're feeling lazy, we love her) is literally your cheat code for tweaking the defaults during container creation 💅

For example:

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 2048 turned into a 0? That's the glow-up ✨

You can also add extra volumes with the --volume flag. It plays by the exact same rules as docker and podman, so the format is --volume SOURCE_PATH:DEST_PATH:MODE.

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

And when the container gets created, you can specify (using the additional-flags) some environment variables that will persist inside the container and stay completely independent from your own environment:

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

The --init-hooks flag is the one for adding commands to the entrypoint (that's the init) of the container. Super useful when you wanna spin up containers that already have a whole set of programs installed, or add users and groups. Iconic behavior fr fr:

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

Then there's --init, which is giving container that runs its own separate init system. Like, actual systemd inside. For example:

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 you'll be able to use normal systemd units, no cap:

~$ 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: turning on --init will disable host's process integration. From inside the container you will not be able to see or manage host's processes. This is needed because /sbin/init must be pid 1. That's just how it is, no negotiating 🫶

And if you wanna 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 for making system containers — the kind where the container acts way more like a full VM than an application-container. Inside you'll have a separate init, user-session, daemons and so on. main character energy, honestly 👑

The --home flag lets you specify a custom HOME for the container. Note that this will NOT prevent the mount of the host's home directory — it just makes sure that configs and dotfiles won't litter it. We love a tidy queen 💖

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! Yeah. Real stakes.

💀 The --absolutely-disable-root-password-i-am-really-positively-sure will skip user password setup, leaving it blank. This is genuinely dangerous and you really, positively should NOT enable this. Like, the flag name is literally begging you. Listen to her.

From version 1.4.0 of distrobox, when you create a new container, it will also generate an entry in the applications list. Slay ✨

🦋 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)

Distrobox — Mar 2026 — DISTROBOX-CREATE(1)

👑 DISTROBOX-ENTER(1) — User Manual 👑

🎀 NAME 🎀

distrobox enter
distrobox-enter

💜 DESCRIPTION 💜

distrobox-enter is the one that takes care of entering the container with the name you specified. By default the command it executes is your SHELL, but bestie you can specify different shells, or entire commands to run. And if you're using it inside a script, an application, or a service, you can specify the --headless mode to disable tty and interactivity. Very demure, very mindful.

✨ SYNOPSIS ✨

distrobox enter

--name, -n — name for the distrobox (default: my-distrobox)
--, -e — end arguments, execute the rest as the command to execute at login (default: default ${USER}'s shell)
--no-tty, -T — do not instantiate a tty
--no-workdir, -nw — always start the container from the container's home directory
--additional-flags, -a — additional flags to pass to the container manager command
--help, -h — show this message
--root, -r — launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred way over "sudo distrobox" (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)
--dry-run, -d — only print the container manager command generated
--verbose, -v — show more verbosity
--version, -V — show version

🍓 EXAMPLES 🍓

Enter a distrobox named "example":

distrobox-enter example

Enter a distrobox while specifying a command:

distrobox-enter --name fedora-toolbox-35 -- bash -l
distrobox-enter my-alpine-container -- sh -l

Use additional podman/docker/lilipod flags while entering a distrobox:

distrobox-enter --additional-flags "--preserve-fds" --name test -- bash -l

Specify additional environment variables while entering a distrobox:

distrobox-enter --additional-flags "--env MY_VAR=value" --name test -- bash -l
MY_VAR=value distrobox-enter --additional-flags "--preserve-fds" --name test -- bash -l

You can also use environment variables to specify the container manager and the container name:

DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-enter

🌸 ENVIRONMENT VARIABLES 🌸

DBX_CONTAINER_NAME
DBX_CONTAINER_MANAGER
DBX_SKIP_WORKDIR
DBX_SUDO_PROGRAM

🌟 EXTRA 🌟

This command is used to enter the distrobox itself. Personally, I just create multiple profiles in my gnome-terminal to have multiple distros accessible. It's giving organized 💅

The --additional-flags or -a is useful to modify the default command when executing in the container. For example:

distrobox enter -n dev-arch --additional-flags "--env my_var=test" -- printenv &| grep my_var
my_var=test

This is possible also using normal env variables:

my_var=test distrobox enter -n dev-arch --additional-flags -- printenv &| grep my_var
my_var=test

If you'd like to enter a rootful container having distrobox use a program other than sudo to run podman/docker/lilipod as root, such as pkexec or doas, you may specify it with the DBX_SUDO_PROGRAM environment variable. For example, to use doas to enter a rootful container:

DBX_SUDO_PROGRAM="doas" distrobox enter -n container --root

Additionally, in one of the config file paths that distrobox supports, such as ~/.distroboxrc, you can also append the line distrobox_sudo_program="doas" (for example) to always run distrobox commands involving rootful containers using doas.

Distrobox — Mar 2026 — DISTROBOX-ENTER(1)

🦋 DISTROBOX-EPHEMERAL(1) — User Manual 🦋

🎀 NAME 🎀

distrobox ephemeral
distrobox-ephemeral

💜 DESCRIPTION 💜

distrobox-ephemeral creates a temporary distrobox that is automatically destroyed when the command is terminated. Like, it lives fast and dies young 😭 so iconic of her.

✨ SYNOPSIS ✨

distrobox ephemeral

--root, -r — launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred way over "sudo distrobox" (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)
--verbose, -v — show more verbosity
--help, -h — show this message
--, -e — end arguments, execute the rest as the command to execute at login (default: default ${USER}'s shell)
--version, -V — show version

🍓 EXAMPLES 🍓

distrobox-ephemeral --image alpine:latest -- cat /etc/os-release
distrobox-ephemeral --root --verbose --image alpine:latest --volume /opt:/opt

You can also use flags from distrobox-create to customize the ephemeral container to run. Yes bestie, you get to decorate her before she vanishes 🌈

🌈 SEE ALSO 🌈

distrobox-create --help
man distrobox-create

🌸 ENVIRONMENT VARIABLES 🌸

distrobox-ephemeral calls distrobox-create, SEE ALSO distrobox-create(1) for a list of supported environment variables to use.

Distrobox — Mar 2026 — DISTROBOX-EPHEMERAL(1)

⭐ DISTROBOX-EXPORT(1) — User Manual ⭐

✨ NAME ✨

distrobox-export 💖

🦋 DESCRIPTION 🦋

okay so. application and binary exporting. that's the whole thing bestie 🫶

distrobox-export is the one that takes care of exporting an app or a binary from the container over to the host. no cap.

and once it's exported? the app is just easily available in your normal launcher, zero drama, and it will automatically be launched from the container it is exported from. it's giving seamless. it's giving you-forgot-it-was-even-in-a-container. 💅✨

🎀 SYNOPSIS 🎀

distrobox-export

--app, -a — name of the application to export, or an absolute path to the desktopfile to export
--bin, -b — absolute path of the binary to export
--list-apps — list the applications exported from this container
--list-binaries — list the binaries exported from this container, use -ep to specify custom paths to search
--delete, -d — delete an exported application or binary
--export-label, -el — label to add to the exported application name. use "none" to disable. defaults to (on $container_name)
--export-path, -ep — path where to export the binary
--extra-flags, -ef — extra flags to add to the command
--enter-flags, -nf — flags to add to distrobox-enter
--sudo, -S — specify if the exported item should be run as sudo
--help, -h — show this message
--verbose, -v — show more verbosity
--version, -V — show version

so like, you're probably gonna want to install graphical applications or CLI tools inside your distrobox, right? and using distrobox-export from inside the container is literally how you get to use them from the host itself. that's the whole trick. 🪄

🍓 EXAMPLES 🍓

distrobox-export --app mpv [--extra-flags "flags"] [--delete] [--sudo]
distrobox-export --bin /path/to/bin [--export-path ~/.local/bin] [--extra-flags "flags"] [--delete] [--sudo]

🌸 App export example 🌸

distrobox-export --app abiword

this tool will simply copy the original .desktop files along with the needed icons, add the prefix /usr/local/bin/distrobox-enter -n distrobox_name -e ... to the commands to run, and save them in your home so they can be used directly from the host as a normal app. iconic behaviour honestly. 👑

distrobox-export --app /opt/application/my-app.desktop

this one skips the whole searching-for-the-desktopfile-in-canonical-paths situation, and just uses the file path you handed it. periodt.

🧚 Binary export example 🧚

distrobox-export --bin /usr/bin/code --extra-flags "--foreground" --export-path $HOME/.local/bin

for binaries you have to tell it where to put the thing (--export-path), and the tool will create a little wrapper script that will distrobox-enter -e from the host for the desired binary. super handy with direnv if you wanna have different versions of the same binary based on your env or your project. iykyk 💜

the exported binaries will be exported in the “–export-path” of choice as a wrapper script that acts naturally both on the host and in the container. best of both worlds fr fr.

✨ Additional flags ✨

you can specify additional flags to add to the command! like, say you wanna export an electron app — you could add the “–foreground” flag to the command:

distrobox-export --app atom --extra-flags "--foreground"
distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --extra-flags "-p"

this works for binaries and apps. and heads up: extra flags are only used when the exported app or binary is used from the host — using them inside the container will not include them. noted. 📝

🎀 Unexport 🎀

the option “–delete” will un-export an app or binary:

distrobox-export --app atom --delete
distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --delete

💜 Run as root in the container 💜

the option “–sudo” will launch the exported item as root inside the distrobox. 🔥

🦋 Notes 🦋

note you can use –app OR –bin but not together. 🚫

[IMAGE: app-export] app-export

NOTE: some electron apps such as vscode and atom need additional flags to work from inside the container, use the --extra-flags option to provide a series of flags, for example:

distrobox-export --app atom --extra-flags "--foreground"

Distrobox · Mar 2026 · DISTROBOX-EXPORT(1)

✨ NAME ✨

distrobox generate-entry 🎀

🌈 DESCRIPTION 🌈

distrobox-generate-entry will create a desktop icon for one of the available distroboxes. and get this — it will then be deleted when you remove the matching distrobox. self-cleaning, we love a low-maintenance icon. ✨

🦋 SYNOPSIS 🦋

distrobox generate-entry

--help, -h — show this message
--all, -a — perform for all distroboxes
--delete, -d — delete the entry
--icon, -i — specify a custom icon [/path/to/icon] (default auto)
--root, -r — perform on rootful distroboxes
--verbose, -v — show more verbosity
--version, -V — show version

🍓 EXAMPLES 🍓

generate an entry for a container:

distrobox generate-entry my-container-name

specify a custom icon for the entry:

distrobox generate-entry my-container-name --icon /path/to/icon.png

generate an entry for all distroboxes:

distrobox generate-entry --all

delete an entry:

distrobox generate-entry container-name --delete

Distrobox · Mar 2026 · DISTROBOX-GENERATE-ENTRY(1)

✨ NAME ✨

distrobox-host-exec 💅

🌸 DESCRIPTION 🌸

distrobox-host-exec lets you execute a command on the host, while you're inside of a container. yes really. reaching back out through the wall like it's nothing. 🫶

under the hood, distrobox-host-exec uses host-spawn, a project that lets us execute commands back on the host. if the tool is not found, the user will be prompted to install it. no silent failures here bestie. 👀

🎀 SYNOPSIS 🎀

just pass to “distrobox-host-exec” any command and all its arguments, if any.

--help, -h — show this message
--verbose, -v — show more verbosity
--version, -V — show version
--yes, -Y — automatically answer yes to prompt:
- host-spawn will be installed on the guest system if host-spawn is not detected.
- this behaviour is default when running in a non-interactive shell.

if no command is provided, it will execute “$SHELL”. 🐚

alternatively, you can symlink a command name to distrobox-host-exec and then call that command by its name on the host, while inside of a container. sneaky. genius. iconic. ⭐

🍓 EXAMPLES 🍓

🌸 Run individual commands 🌸

distrobox-host-exec ls
distrobox-host-exec bash -l
distrobox-host-exec flatpak run org.mozilla.firefox
distrobox-host-exec podman ps -a

💜 Drop into host shell 💜

~$: distrobox-host-exec # No command, executes "$SHELL" on the host
~$: distrobox-host-exec # This command now runs on the host
You must run  distrobox-host-exec inside a container!

🧚 Symlinking host commands 🧚

use the host command name to create a symlink to distrobox-host-exec. you can then call the host command from within the container. 🪄

~$: git # We do not have git in the container
bash: git: command not found
~$: sudo ln -s /usr/bin/distrobox-host-exec /usr/local/bin/git
~$: git version
git version 2.51.1

you can control podman on the host from within the container as follows:

~$: ln -s /usr/bin/distrobox-host-exec /usr/local/bin/podman
~$: ls -l /usr/local/bin/podman
lrwxrwxrwx. 1 root root 51 Jul 11 19:26 /usr/local/bin/podman -> /usr/bin/distrobox-host-exec
~$: podman version
...this is executed on host...

Distrobox · Mar 2026 · DISTROBOX-HOST-EXEC(1)

✨ NAME ✨

distrobox-init 🌸

🦋 DESCRIPTION 🦋

init the distrobox (not to be launched manually). okay emphasis on that, bestie. 🙈

distrobox-init is the entrypoint of a created distrobox. note that this HAS to run from inside a distrobox — it will not work if you run it from your host. hard no. 🚫

this is not intended to be used manually, but instead used by distrobox-create to set up the container's entrypoint. so like, it's backstage crew. still important though. 💅

distrobox-init will take care of installing missing dependencies (eg. sudo), set up the user and groups, and mount directories from the host to ensure the tight integration. it does a lot actually. main character energy but behind the scenes. ✨

🎀 SYNOPSIS 🎀

distrobox-init

--name, -n — user name
--user, -u — uid of the user
--group, -g — gid of the user
--home, -d — path/to/home of the user
--help, -h — show this message
--additional-packages — packages to install in addition
--init, -I — whether to use or not init
--pre-init-hooks — commands to execute prior to init
--nvidia — try to integrate host's nVidia drivers in the guest
--upgrade, -U — run init in upgrade mode
--verbose, -v — show more verbosity
--version, -V — show version
-- — end arguments execute the rest as command to execute during init

🍓 EXAMPLES 🍓

distrobox-init --name test-user --user 1000 --group 1000 --home /home/test-user
distrobox-init --upgrade

Distrobox · Mar 2026 · DISTROBOX-INIT(1)

✨ NAME ✨

distrobox list distrobox-list 👑

🌈 DESCRIPTION 🌈

distrobox-list lists the available distroboxes. it detects them and lists them separately from the rest of the normal containers. so your distroboxes get their own lil spotlight. as they deserve. 💖

🦋 SYNOPSIS 🦋

distrobox list

--help, -h — show this message
--no-color — disable color formatting
--root, -r — launch podman/docker/lilipod with root privileges. note that if you need root this is the preferred way over "sudo distrobox" (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)
--verbose, -v — show more verbosity
--version, -V — show version

Distrobox · Mar 2026 · DISTROBOX-LIST(1)

🌸 EXAMPLES 🌸

Okay bestie, back to distrobox-list for one sec — here's how you actually run it:

distrobox-list

And you can absolutely yeet the container manager choice in through an env var, like so:

DBX_CONTAINER_MANAGER="docker" distrobox-list

💖 ENVIRONMENT VARIABLES 💖

These are the knobs the page says you get to play with:

DBX_CONTAINER_MANAGER — tells distrobox which container manager you're vibing with.
DBX_SUDO_PROGRAM — the program used to get root privileges.
and there's an image here in the original page: [IMAGE: image] image 🖼️ (yes literally, that's what it says, not me being cute)

And that's a wrap on this one — source and date: Distrobox, Mar 2026, page DISTROBOX-LIST(1). 💅

────────────────────────────────────────────────────────────────────────────────

👑 DISTROBOX-RM(1) — User Manual

NAME

distrobox rm distrobox-rm

DESCRIPTION

distrobox-rm deletes one of the available distroboxes. Gone. Poof. It's giving ✨closure✨.

SYNOPSIS

distrobox rm

--all, -a — delete all distroboxes (yes, all of them, bestie, be so serious before you type this)
--force, -f — force deletion
--rm-home — remove the mounted home if it differs from the host user's one
--root, -r — launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred way over sudo distrobox (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)
--help, -h — show this message
--verbose, -v — show more verbosity
--version, -V — show version

EXAMPLES

distrobox-rm container-name [--force] [--all]

You can also use environment variables to specify container manager and name:

DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-rm

ENVIRONMENT VARIABLES

DBX_CONTAINER_MANAGER
DBX_CONTAINER_NAME
DBX_NON_INTERACTIVE
DBX_SUDO_PROGRAM

Source and date for this one: Distrobox, Mar 2026, page DISTROBOX-RM(1). 🎀

🦋 DISTROBOX-STOP(1) — User Manual

NAME

distrobox stop distrobox-stop

DESCRIPTION

distrobox-stop stops a running distrobox. 🛑

Here's the lore, bestie: distroboxes are left running, even after exiting out of them, so that subsequent enters are really quick. This is how they can be stopped. No cap — that's the whole reason this command exists.

SYNOPSIS

distrobox stop

--all, -a — stop all distroboxes
--yes, -Y — non-interactive, stop without asking
--help, -h — show this message
--root, -r — launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred way over sudo distrobox (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)
--verbose, -v — show more verbosity
--version, -V — show version

EXAMPLES

distrobox-stop container-name1 container-name2
distrobox-stop container-name
distrobox-stop --all

You can also use environment variables to specify container manager and name:

DBX_CONTAINER_MANAGER="docker" DBX_CONTAINER_NAME=test-alpine distrobox-stop

ENVIRONMENT VARIABLES

DBX_CONTAINER_MANAGER
DBX_CONTAINER_NAME
DBX_NON_INTERACTIVE
DBX_SUDO_PROGRAM

Source and date, one more time: Distrobox, Mar 2026, page DISTROBOX-STOP(1). 🌈

🔥 DISTROBOX-UPGRADE(1) — User Manual

NAME

distrobox-upgrade

DESCRIPTION

distrobox-upgrade will enter the specified list of containers and will perform an upgrade using the container's package manager. It's the "go freshen up, bestie" command fr fr. ✨

SYNOPSIS

distrobox upgrade

--help, -h — show this message
--all, -a — perform for all distroboxes
--running — perform only for running distroboxes
--root, -r — launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred way over sudo distrobox (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)
--verbose, -v — show more verbosity
--version, -V — show version

EXAMPLES

Upgrade all distroboxes:

distrobox-upgrade --all

Upgrade all running distroboxes:

distrobox-upgrade --all --running

Upgrade a specific distrobox:

distrobox-upgrade alpine-linux

Upgrade a list of distroboxes:

distrobox-upgrade alpine-linux ubuntu22 my-distrobox123

Automatically update all distro. 🤖

You can create a systemd service to perform distrobox-upgrade automatically, this example shows how to run it daily:

~/.config/systemd/user/distrobox-upgrade.service

[Unit]
Description=distrobox-upgrade Automatic Update

[Service]
Type=simple
ExecStart=distrobox-upgrade --all
StandardOutput=null

~/.config/systemd/user/distrobox-upgrade.timer

[Unit]
Description=distrobox-upgrade Automatic Update Trigger

[Timer]
OnBootSec=1h
OnUnitInactiveSec=1d

[Install]
WantedBy=timers.target

Then simply do a systemctl --user daemon-reload && systemctl --user enable --now distrobox-upgrade.timer

And that's the whole page, bestie!! 🫶 Every last option, env var, example and systemd unit accounted for, not a single crumb left behind. This came from the Distrobox source, dated Mar 2026, closing out page DISTROBOX-UPGRADE(1) — the final one of the set. Go forth and upgrade your little containers, you absolute icon. 👑💜

📦 where this page comes from

alpine 3.24: distrobox-doc 1.8.2.5-r0 · GPL-3.0-only
arch rolling: distrobox 1.8.2.5-1 · GPL-3.0-only
epel 10: distrobox 1.8.2.5-1.el10_3 · GPL-3.0-only
epel 9: distrobox 1.8.2.5-1.el9 · GPL-3.0-only
fedora 43: distrobox 1.8.2.5-1.fc43 · GPL-3.0-only
fedora 44: distrobox 1.8.2.5-1.fc44 · GPL-3.0-only
nixos 26.05: distrobox 1.8.2.5
nixpkgs unstable: distrobox 1.8.2.5
ubuntu stonking: distrobox 1.8.2.5-1 · GPL-3.0-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms

DISTROBOX-ASSEMBLE(1)

💖 distrobox-assemble(1) — the User Manual, but make it cute 💖

✨ NAME ✨

🌸 DESCRIPTION 🌸

🎀 SYNOPSIS 🎀

🧚 EXAMPLES 🧚

💜 Create

🔁 Replace

🗑️ Remove

👀 Test

👯 Clone

🌈 Available options

⭐ Types legend:

👑 The big list (flag name → type → what she does)

🔥 Advanced example

🧬 Clone example 🧬

🐚 Custom login shell example 🐚

🫂 Include example (inherit fields from another distrobox) 🫂

🌈 COMPATIBILITY 🌈

🫶 SUPPORTED CONTAINER MANAGERS 🫶

🦋 CONTAINERS DISTROS 🦋

🌱 NEW DISTRO SUPPORT

👵 OLDER DISTRIBUTIONS

🎮 GPU ACCELERATION SUPPORT

🎀 NAME

💫 DESCRIPTION

✨ SYNOPSIS ✨

🌸 COMPATIBILITY 🌸

💖 EXAMPLES 💖

🌈 ENVIRONMENT VARIABLES 🌈

🌈 EXTRA 🌈

🦋 NVidia integration 🦋

👑 DISTROBOX-ENTER(1) — User Manual 👑

🎀 NAME 🎀

💜 DESCRIPTION 💜

✨ SYNOPSIS ✨

🍓 EXAMPLES 🍓

🌸 ENVIRONMENT VARIABLES 🌸

🌟 EXTRA 🌟

🦋 DISTROBOX-EPHEMERAL(1) — User Manual 🦋

🎀 NAME 🎀

💜 DESCRIPTION 💜

✨ SYNOPSIS ✨

🍓 EXAMPLES 🍓

🌈 SEE ALSO 🌈

🌸 ENVIRONMENT VARIABLES 🌸

⭐ DISTROBOX-EXPORT(1) — User Manual ⭐

✨ NAME ✨

🦋 DESCRIPTION 🦋

🎀 SYNOPSIS 🎀

🍓 EXAMPLES 🍓

🌸 App export example 🌸

🧚 Binary export example 🧚

✨ Additional flags ✨

🎀 Unexport 🎀

💜 Run as root in the container 💜

🦋 Notes 🦋

✨ NAME ✨

🌈 DESCRIPTION 🌈

🦋 SYNOPSIS 🦋

🍓 EXAMPLES 🍓

✨ NAME ✨

🌸 DESCRIPTION 🌸

🎀 SYNOPSIS 🎀

🍓 EXAMPLES 🍓

🌸 Run individual commands 🌸

💜 Drop into host shell 💜

🧚 Symlinking host commands 🧚

✨ NAME ✨

🦋 DESCRIPTION 🦋

🎀 SYNOPSIS 🎀

🍓 EXAMPLES 🍓

✨ NAME ✨

🌈 DESCRIPTION 🌈

🦋 SYNOPSIS 🦋

🌸 EXAMPLES 🌸

💖 ENVIRONMENT VARIABLES 💖

👑 DISTROBOX-RM(1) — User Manual

NAME

DESCRIPTION