Guide

Distrobox on Shani OS — A Full Mutable Linux Inside an Immutable One

Shrinivas Vishnu Kumbhar · 2026-04-20 · 9 min

Distrobox is the answer to the question every experienced Linux user asks when they encounter an immutable OS: "But what if I need apt install, pacman -S, or a tool that only exists in the AUR?"

Distrobox creates a container running any Linux distribution — Arch, Ubuntu, Fedora, Debian, openSUSE — with that distro's full package manager intact. Your home directory is shared by default. Binaries you install inside can be exported to your host desktop and launcher. The container lives in the @containers Btrfs subvolume, completely independent of the OS. It survives every OS update and rollback untouched.

The result: you have an immutable, reliable, atomic OS as your base, and a full mutable Linux environment available whenever you need one — without any contradiction between the two.

BoxBuddy (pre-installed on both GNOME and KDE editions) provides a clean graphical interface for creating and managing containers without the terminal. Full reference documentation: docs.shani.dev — Distrobox.

---

How Distrobox Works

Distrobox is not a virtual machine. It does not emulate hardware or run a separate kernel. It creates a container using Podman (pre-installed on Shani OS) that shares the host kernel and your home directory. The container has its own package manager, its own /usr, its own installed packages — but your /home/username is the same directory inside and outside the container.

The practical effects:

  • Tools installed inside a container can read and write your project files immediately
  • You never need to copy files between host and container
  • The container starts in under a second
  • Multiple containers of different distros coexist without conflict
  • Containers persist across reboots in @containers

---

BoxBuddy — Graphical Container Management

BoxBuddy is pre-installed on both GNOME and KDE editions. Open it from your application launcher.

BoxBuddy lets you:

  • Create new containers from any distro image with a few clicks
  • Enter containers with a single click
  • See which apps are installed in each container
  • Export apps and binaries to your host launcher
  • Delete containers cleanly

For users who prefer the terminal, everything BoxBuddy does maps directly to distrobox commands — both approaches are shown below.

---

Creating Containers

# Create an Arch Linux container (full pacman + AUR)
distrobox create --name arch-dev --image archlinux:latest

# Create an Ubuntu 24.04 container
distrobox create --name ubuntu-dev --image ubuntu:24.04

# Create a Fedora container
distrobox create --name fedora-dev --image fedora:latest

# Create a Debian container
distrobox create --name debian-stable --image debian:stable

# Create an openSUSE Tumbleweed container
distrobox create --name suse-dev --image opensuse/tumbleweed:latest

# List all containers
distrobox list

The container image is downloaded the first time. Subsequent container creations from the same base image are instant — Podman reuses cached layers.

---

Entering Containers

# Enter a container by name
distrobox enter arch-dev
distrobox enter ubuntu-dev

# Once inside, you are in a full shell of that distro
# Your home directory is the same — /home/username
# You can use the full package manager

# Arch Linux container — full pacman + yay for AUR
sudo pacman -Syu
sudo pacman -S some-package
yay -S some-aur-package    # yay is available after install (see below)

# Ubuntu container — full apt
sudo apt update && sudo apt upgrade
sudo apt install some-package
sudo add-apt-repository ppa:some/ppa
sudo apt install ppa-package

# Fedora container — full dnf
sudo dnf upgrade
sudo dnf install some-package

# Exit the container
exit

---

Setting Up an Arch Container with AUR Access

The AUR (Arch User Repository) is one of the most common reasons experienced Linux users want a full Arch environment on an immutable OS.

# Create and enter an Arch container
distrobox create --name arch-aur --image archlinux:latest
distrobox enter arch-aur

# Inside: update and install base tools
sudo pacman -Syu
sudo pacman -S --needed base-devel git

# Install yay (AUR helper)
git clone https://aur.archlinux.org/yay.git
cd yay && makepkg -si && cd .. && rm -rf yay

# Now use the full AUR
yay -S some-aur-package
yay -S another-tool

# Export a binary to your host
distrobox-export --bin /usr/bin/some-tool
# Now 'some-tool' is available on your host PATH

# Exit
exit

---

Exporting Apps to Your Host Desktop

Distrobox can export installed applications so they appear in your host application launcher and work like native apps — even though they are running inside a container.

# Export a desktop application (creates a .desktop file in ~/.local/share/applications)
distrobox enter ubuntu-dev
distrobox-export --app some-gui-app

# Export a binary to your host PATH
distrobox-export --bin /usr/bin/some-tool

# Export a systemd service (runs inside the container at host boot)
distrobox-export --service some.service

Exported apps appear in GNOME's app grid or KDE's application menu with the container's icon. They launch transparently — you click the icon, the container starts if it is not already running, and the app appears on your screen.

To remove an export:

distrobox-export --app some-gui-app --delete
distrobox-export --bin /usr/bin/some-tool --delete

---

Practical Use Cases

Development Tools That Require make install

Many development tools publish instructions like ./configure && make && sudo make install. On Shani OS, /usr is read-only and this does not work on the host. Inside a Distrobox container, it works exactly as expected:

distrobox enter ubuntu-dev
git clone https://github.com/some/tool.git
cd tool && ./configure && make && sudo make install
# Installed to /usr/local/bin inside the container
distrobox-export --bin /usr/local/bin/tool
# Now available on host

Building and Testing Software for Multiple Distros

# Test a build on Ubuntu
distrobox enter ubuntu-dev
cd ~/projects/myapp
./build.sh

# Test the same build on Fedora
exit
distrobox enter fedora-dev
cd ~/projects/myapp
./build.sh

Your project files are in your home directory — the same path in both containers.

PPAs and Third-Party Repositories

distrobox enter ubuntu-dev

# Add any Ubuntu PPA
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11

distrobox-export --bin /usr/bin/python3.11

Legacy Software

Some software has not been packaged as a Flatpak and has complex system dependencies. If it has a .deb or is in an APT repo:

distrobox enter ubuntu-dev
sudo dpkg -i legacy-app.deb
# or
sudo apt install legacy-app
distrobox-export --app legacy-app

---

Running GUI Apps from Containers

GUI apps run inside Distrobox containers display on your host Wayland or X11 desktop natively — there is no separate X server or VNC involved. They appear as regular windows on your desktop.

distrobox enter ubuntu-dev
# Install a GUI app that is not in Flathub
sudo apt install some-gui-app
some-gui-app  # launches on your host desktop

# Or export it so it appears in your launcher
distrobox-export --app some-gui-app
exit
# From now on, launch from your app menu

---

Managing Multiple Containers

# List all containers and their status
distrobox list

# Stop a running container
distrobox stop arch-dev

# Remove a container (data in your home directory is untouched)
distrobox rm arch-dev

# Remove and delete all data
distrobox rm arch-dev --force

# Upgrade all packages in a container
distrobox enter ubuntu-dev -- sudo apt upgrade -y
distrobox enter arch-dev -- sudo pacman -Syu --noconfirm

Running Commands Without Entering

You can run a single command in a container without entering an interactive shell:

# Run a command in a container
distrobox enter ubuntu-dev -- python3 --version
distrobox enter arch-dev -- yay -Qs some-package

---

Distrobox vs the Full Ecosystem

Distrobox fills the gap that Flatpak, Nix, and AppImage can't: when you need a full mutable Linux environment with apt, pacman, yay, or any distro's native package manager. It coexists with every other ecosystem on Shani OS — containers in @containers, apps in @flatpak, packages in @nix, all independent and all surviving OS updates.

The Shani OS Software Ecosystem has the full decision flowchart and comparison table.

---

Storage and Performance

Distrobox containers live in the @containers Btrfs subvolume mounted at /var/lib/containers. Podman manages the OCI image layers there.

Btrfs zstd compression applies to @containers, so container storage is compressed automatically. The bees background deduplication daemon also runs across all subvolumes — layers shared between containers (common base images) are deduplicated at the block level.

To see how much storage your containers use:

# Container sizes
podman system df
distrobox list

# Btrfs compressed size
sudo compsize /var/lib/containers

To clean up unused container images:

podman system prune -af

---

Troubleshooting

Container fails to start:

# Check Podman logs
podman ps -a
podman logs <container-id>

# Reinitialise a broken container
distrobox rm arch-dev --force
distrobox create --name arch-dev --image archlinux:latest

Exported app does not appear in launcher:

# Force a desktop database update
update-desktop-database ~/.local/share/applications

# Check the exported .desktop file
ls ~/.local/share/applications/ | grep -i appname
cat ~/.local/share/applications/appname.desktop

Home directory permissions issue inside container:

The container shares your host home directory and user ID. Permissions should always match. If something is wrong:

# Check UID inside vs outside
distrobox enter mycontainer -- id
id  # on host — both should show the same UID

Full troubleshooting reference: docs.shani.dev — Distrobox.

---

Resources

---

Built in India 🇮🇳 · Immutable · Atomic · Zero Telemetry