| name | distrobox |
| description | Create, enter, and manage Distrobox containers for mutable package installation on Bluefin. |
| domain | sysadmin |
| tags | ["distrobox","containers","packages","linux"] |
| version | 2.0 |
Distrobox
Distrobox runs Linux distribution containers that integrate seamlessly with the host OS —
sharing the home directory, display server, audio, DBus, and hardware devices. Use it to
install RPM/DEB packages, run distribution-specific toolchains, or export apps/binaries to
the host without touching the immutable base image.
When to Use
- Installing RPM/DEB packages not available as Flatpaks or Homebrew formulas
- Running distribution-specific tools (
dnf, apt, yum, pacman) without altering the host
- Toolchains (Go, Rust, Python envs, Node versions) that need
root-level package management
- GUI apps that lack a Flatpak release or whose Flatpak is broken/outdated
- NVIDIA-accelerated workloads that need full Linux library stacks (ML, CUDA)
- Reproducible developer environments defined as code (
distrobox-assemble)
When NOT to Use
- GUI apps with a good Flatpak release — prefer
flatpak install (better sandboxing, auto-updates)
- CLI tools available as Homebrew formulas — prefer
brew install (lighter weight, no container overhead)
- One-off commands that don't need a persistent container — use
podman run --rm
- Anything requiring a real system daemon inside the container (use a VM instead)
Quick Start
distrobox create --name mybox --image registry.fedoraproject.org/fedora:latest
distrobox enter mybox
sudo dnf install git vim golang
distrobox-export --app code
distrobox-export --bin /usr/bin/go --export-path ~/.local/bin
exit
distrobox list
distrobox stop mybox
distrobox rm mybox
distrobox-assemble — Declarative Container Definitions
distrobox-assemble lets you define containers as code in an INI file and recreate them
idempotently. Commit distrobox.ini to your dotfiles for reproducible environments.
distrobox.ini:
[fedora-dev]
image=registry.fedoraproject.org/fedora:latest
pull=true
root=false
replace=false
init=false
additional_packages=git vim curl golang nodejs
[ubuntu-tools]
image=docker.io/library/ubuntu:22.04
pull=true
root=false
additional_packages=build-essential python3-pip
distrobox-assemble create --file distrobox.ini
distrobox-assemble rm --file distrobox.ini
distrobox-assemble create --file distrobox.ini --dry-run
Key INI options:
| Option | Effect |
|---|
image | OCI image reference |
pull=true | Always pull the latest image before creating |
replace=false | Don't destroy and recreate if container already exists |
init=false | Skip running the init script (faster; set true for systemd-based images) |
additional_packages | Space-separated list installed during first boot |
home | Override the container home directory path |
volume | Extra volume mounts (/host/path:/container/path) |
pre_init_hook | Shell command run before package installation |
post_init_hook | Shell command run after package installation |
distrobox init — First-Boot Setup Scripts
When you need to run custom setup logic (dotfiles, config, tool downloads) the first time a
container is created, pass a script via --init-hooks or the init_hooks INI key.
distrobox create \
--name dev \
--image registry.fedoraproject.org/fedora:latest \
--init-hooks "curl -fsSL https://raw.githubusercontent.com/you/dotfiles/main/setup.sh | bash"
Or in distrobox.ini:
[dev]
image=registry.fedoraproject.org/fedora:latest
additional_packages=git curl
post_init_hook=curl -fsSL https://example.com/setup.sh | bash
The hook runs once on first enter. Destroying and recreating the container reruns it.
distrobox-generate-entry — Manual .desktop Entry Creation
distrobox-export --app <name> handles most cases, but sometimes the app name doesn't match
the .desktop file, or the app isn't installed to a standard location.
Use distrobox-generate-entry to create the entry manually.
find /usr/share/applications -name "*.desktop" | grep -i myapp
distrobox-generate-entry myapp --container mybox --export-label " (mybox)"
distrobox-generate-entry myapp --container mybox --delete
distrobox-enter vs distrobox run
| distrobox enter | distrobox run |
|---|
| Use case | Interactive shell session | Run a single command non-interactively |
| Allocates TTY | Yes | No (unless -- passes -t) |
| Shell | Login shell (reads .bashrc, etc.) | Direct exec, minimal environment |
| Exit code | Shell's exit code | Command's exit code (propagated cleanly) |
| Typical use | Development work, exploration | Scripting, CI one-shots, cron jobs |
Run a single command non-interactively: distrobox run --name mybox -- go test ./...
Home Directory and Volumes
Default: Shared Home
By default, Distrobox bind-mounts the host's $HOME into the container at the same path —
files created in either environment are immediately visible in both.
Isolated Home: --home
Use --home to give a container its own private home directory (no host dotfiles):
distrobox create \
--name clean-box \
--image registry.fedoraproject.org/fedora:latest \
--home /home/jorge/containers/clean-box
Extra Volumes: --volume
Mount additional host directories into the container with Docker-style syntax:
distrobox create \
--name dev \
--image registry.fedoraproject.org/fedora:latest \
--volume /mnt/data:/data:ro \
--volume /run/docker.sock:/run/docker.sock
In distrobox.ini:
[dev]
image=registry.fedoraproject.org/fedora:latest
volume=/mnt/data:/data:ro /run/docker.sock:/run/docker.sock
Mount options (ro, rw, z, Z) follow OCI/Podman conventions.
Container Image Guidance
Recommended on Bluefin: Fedora
registry.fedoraproject.org/fedora:latest
Why Fedora is preferred:
- Same package ecosystem as the Bluefin host (RPM-based);
dnf is familiar
- SELinux labels are compatible out of the box
- Fedora is the upstream of RHEL — packages are current and well-maintained
- Matches the Developer Experience (DX) edition's toolchain philosophy
Ubuntu — When to Use
docker.io/library/ubuntu:22.04
docker.io/library/ubuntu:24.04
Use when a tool/SDK is only officially supported on Ubuntu, you need .deb builds,
or your project's CI is Ubuntu-based.
Arch Linux — When to Use
docker.io/library/archlinux:latest
Use when you need bleeding-edge package versions or AUR packages
(paru/yay work inside the container).
Image Version Pinning
For reproducible environments, pin to a specific tag rather than latest:
[fedora-dev]
image=registry.fedoraproject.org/fedora:41
pull=false
Exporting systemd Services
Export a service running inside a container so the host systemd manages it.
distrobox enter mybox
sudo dnf install syncthing
systemctl --user enable syncthing.service
distrobox-export --service syncthing.service
exit
systemctl --user start syncthing.service
systemctl --user enable syncthing.service
The exported .service file lands in ~/.config/systemd/user/ and wraps the in-container
process transparently. To remove: distrobox-export --service syncthing.service --delete && systemctl --user daemon-reload
GPU Passthrough (NVIDIA Variant)
Users on bluefin-nvidia can pass the GPU into a container for CUDA workloads, ML
training, or GPU-accelerated rendering.
distrobox create \
--name nvidia-box \
--image registry.fedoraproject.org/fedora:latest \
--nvidia
distrobox enter nvidia-box
nvidia-smi
nvcc --version
python3 -c "import torch; print(torch.cuda.is_available())"
Requirements:
- Host must be on
bluefin-nvidia (NVIDIA drivers pre-installed)
- Container and host NVIDIA driver versions must match — Distrobox bind-mounts the host
driver stack; version mismatches cause failures
--nvidia also sets NVIDIA_VISIBLE_DEVICES and NVIDIA_DRIVER_CAPABILITIES
Install CUDA inside the container (Fedora):
sudo dnf install cuda-toolkit
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
Bluefin Integration
Ptyxis Terminal — Native Distrobox Sidebar
Ptyxis (default terminal on Bluefin) has first-class Distrobox support — all running
containers appear as selectable shell profiles in the sidebar. No CLI needed.
- Click the + (new tab) dropdown → select a container name
- Each tab shows which container (or host) it's running in
- No configuration required — Ptyxis auto-discovers Distrobox containers
Distroshelf — GUI Container Manager
flatpak install flathub io.github.ranfdev.DistroShelf
GNOME GUI for creating, starting, stopping, and deleting containers, and opening terminals
into them with one click. Changes are reflected in the CLI immediately.
distrobox-upgrade — Updating All Containers
distrobox-upgrade --all
distrobox-upgrade mybox ubuntu-tools
distrobox-upgrade --all --pull
Runs the appropriate package manager (dnf upgrade, apt upgrade, pacman -Syu, etc.)
inside each container non-interactively. Schedule with a systemd timer for automated maintenance.
Troubleshooting
Container Won't Start
distrobox list
podman ps -a | grep mybox
podman logs mybox
podman stop mybox && podman rm mybox
distrobox create --name mybox --image registry.fedoraproject.org/fedora:latest
Corrupted image? Force re-pull:
podman pull registry.fedoraproject.org/fedora:latest
distrobox rm mybox && distrobox create --name mybox --image registry.fedoraproject.org/fedora:latest
Exported App Not Appearing in Launcher
ls ~/.local/share/applications/ | grep myapp
update-desktop-database ~/.local/share/applications/
If the app name is wrong, use distrobox-generate-entry manually (see above).
Log out and back in if GNOME Shell still doesn't pick it up.
Exported Binary Not on PATH
ls ~/.local/bin/
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
Missing Packages / Wrong Package Manager
| Container base | Install command |
|---|
| Fedora / RHEL | sudo dnf install <pkg> |
| Ubuntu / Debian | sudo apt update && sudo apt install <pkg> |
| Arch | sudo pacman -Syu <pkg> |
Distrobox grants passwordless sudo inside the container by default. If sudo is absent,
check /etc/sudoers.d/ or run su - with an empty root password.
SELinux Volume Permission Errors
Add :z (shared) or :Z (private) to volume mounts:
distrobox create --name dev --image fedora:latest --volume /mydata:/data:Z