distrobox

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

# 1. Create a Fedora container (recommended on Bluefin)
distrobox create --name mybox --image registry.fedoraproject.org/fedora:latest

# 2. Enter and install packages
distrobox enter mybox
sudo dnf install git vim golang

# 3. Export an app so it appears in the GNOME app grid
distrobox-export --app code          # GUI app
distrobox-export --bin /usr/bin/go --export-path ~/.local/bin   # CLI binary

# 4. Exit the container
exit

# Other lifecycle commands
distrobox list           # show all containers
distrobox stop mybox     # stop a running container
distrobox rm mybox       # delete a container (data in home is preserved)

---

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

# Create all containers defined in the file
distrobox-assemble create --file distrobox.ini

# Destroy all containers defined in the file
distrobox-assemble rm --file distrobox.ini

# Dry-run to preview what would happen
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 the .desktop file inside the container
find /usr/share/applications -name "*.desktop" | grep -i myapp

# Generate a .desktop entry pointing to this container
distrobox-generate-entry myapp --container mybox --export-label " (mybox)"

# Remove a previously generated entry
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 \          # read-only data share
  --volume /run/docker.sock:/run/docker.sock   # Docker socket passthrough

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   # LTS
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.

# Inside the container: install and enable the service
distrobox enter mybox
sudo dnf install syncthing
systemctl --user enable syncthing.service

# Export to host
distrobox-export --service syncthing.service
exit

# On the host
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          # verify GPU is visible
nvcc --version      # if CUDA toolkit installed
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
# PyTorch
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              # upgrade all containers
distrobox-upgrade mybox ubuntu-tools # upgrade specific containers
distrobox-upgrade --all --pull       # pull latest images first, then upgrade

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                   # check status
podman ps -a | grep mybox        # Podman's view
podman logs mybox                # inspect logs

# Force-remove stuck container and recreate
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            # verify .desktop was created
update-desktop-database ~/.local/share/applications/    # refresh database

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/    # confirm binary is there
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