Content:

1. What is Distrobox?
2. Distrobox cheatsheet

Distrobox is a powerful containerization tool for Linux that allows you to run different Linux distributions inside containers while maintaining seamless integration with your host system. It’s built on top of container engines like Podman or Docker and serves as a wrapper that makes container management much more user-friendly for desktop use cases.

Core Concept and Purpose

Distrobox addresses a common problem: you might want to use software from different Linux distributions without the complexity of dual-booting, virtual machines, or the limitations of traditional containers. For example, you might be running Fedora but need access to Ubuntu’s package repositories, or you’re on a stable distribution like Debian but occasionally need cutting-edge software from Arch Linux.

Traditional containers are designed for server applications and are quite isolated from the host system. Distrobox breaks down many of these barriers, creating containers that feel more like lightweight, integrated environments rather than isolated sandboxes.

How Distrobox Works

When you create a Distrobox container, it automatically sets up several integrations with your host system. The container shares your home directory, which means your personal files, configurations, and data are immediately available inside the container. Your user account is replicated inside the container with the same username, user ID, and group memberships, ensuring file permissions work correctly.

The tool also handles graphics integration automatically. Applications running inside Distrobox containers can display on your host desktop using X11 or Wayland, complete with hardware acceleration support. Audio systems like PulseAudio and PipeWire are also integrated, so containerized applications can play sound normally.

Network access is seamless - containers use the host’s network stack, so internet connectivity and local network resources work without additional configuration. USB devices, printers, and other hardware are accessible from within containers when needed.

Installation and Setup

Installing Distrobox is straightforward. On most distributions, you can download the installation script directly from the project’s repository or install it through your package manager if available. The tool requires either Podman or Docker as the underlying container engine, with Podman being the preferred choice for most desktop users due to its rootless operation.

After installation, you need minimal configuration. Distrobox automatically detects your container engine and sets up the necessary components. The first time you create a container, it may take a few minutes to download the base image, but subsequent operations are much faster.

Creating and Managing Containers

Creating a new container is simple with commands like distrobox create --name mycontainer --image ubuntu:22.04. This creates an Ubuntu 22.04 container that you can enter using distrobox enter mycontainer. Inside the container, you have full access to Ubuntu’s package manager and repositories while still being able to access your home directory and run graphical applications.

You can create multiple containers for different purposes - perhaps an Arch container for accessing the AUR, a CentOS container for enterprise development, and a Debian container for stable server software. Each container maintains its own package installation and configuration while sharing your user data.

Container management includes features like automatic updates, where Distrobox can keep your container images current. You can also export applications from containers to your host desktop, making them appear in your application menu as if they were natively installed.

Application Integration

One of Distrobox’s most impressive features is application integration. When you install software inside a container, you can export it to your host system using distrobox-export. This creates desktop entries and menu items that launch the containerized application seamlessly. From the user’s perspective, the application behaves exactly like native software.

This integration extends to command-line tools as well. You can export terminal applications and scripts, making them available system-wide. File associations work correctly, so double-clicking a file can open it with a containerized application.

Development Workflows

Distrobox excels in development scenarios. You can create containers with specific development environments - perhaps a container with Node.js and npm for web development, another with Python and data science libraries, and yet another with Go and Docker for cloud development. Each environment remains isolated while sharing your source code through the mounted home directory.

Version management becomes much easier when you can quickly spin up containers with different versions of programming languages, databases, or development tools. Testing software across different distributions is also simplified since you can quickly create containers based on various Linux distributions.

Package Management Benefits

Different Linux distributions have different package managers and repositories. With Distrobox, you can access the package ecosystems of multiple distributions simultaneously. Need a package that’s only available in the AUR? Create an Arch container. Want the latest versions of development tools? Use a Fedora or openSUSE Tumbleweed container. Need enterprise-grade stability? Set up a RHEL or CentOS container.

This approach also helps with package conflicts. If you need two versions of the same library or conflicting packages, you can install them in separate containers without affecting your host system or each other.

Security and Isolation

While Distrobox containers are more integrated than traditional containers, they still provide meaningful isolation. Each container has its own filesystem, process space, and package installation. Malicious or buggy software inside a container has limited ability to affect the host system or other containers.

However, the extensive integration means Distrobox containers are not suitable for running untrusted software. The shared home directory and hardware access mean that malicious software could potentially access your personal data. Distrobox is designed for running software you trust in isolated environments, not for security sandboxing.

Performance Considerations

Distrobox containers have minimal performance overhead since they use your host kernel and share most system resources. Application startup times are nearly identical to native applications, and runtime performance is essentially the same as running software directly on the host.

Storage overhead is also minimal thanks to container image layering. Multiple containers based on the same distribution share common layers, so creating several Ubuntu containers doesn’t multiply storage usage by the number of containers.

Use Cases and Practical Applications

Common use cases include software development across multiple environments, accessing software not available in your distribution’s repositories, testing applications on different distributions, and maintaining clean separation between different types of work or projects.

Educational users benefit from being able to quickly set up and tear down different Linux environments for learning purposes. System administrators can test scripts and configurations across different distributions without needing multiple virtual machines.

Gaming enthusiasts use Distrobox to access game packages from different distributions or to maintain separate environments for different game stores and their dependencies.

Limitations and Considerations

Distrobox isn’t suitable for all scenarios. System-level software, kernel modules, and services that need to interact directly with the host system won’t work well in containers. Some applications that expect specific system configurations might not function correctly.

The integration features mean that Distrobox containers aren’t as portable as traditional containers. They’re designed to work with your specific host system rather than being deployable anywhere.

Resource usage can accumulate if you create many containers, though the overhead per container is relatively small. Managing many containers can become complex, requiring good organizational practices.

Integration with Host System Services

Distrobox containers can interact with many host system services. Desktop notifications work correctly, system themes are often inherited, and clipboard sharing functions normally. File managers can browse container filesystems, and version control systems work seamlessly across the container boundary.

Some containers can even access host system services like systemd user services, depending on the configuration and the specific services involved.

Distrobox represents a middle ground between full system virtualization and traditional application containers, optimized specifically for desktop Linux users who want the benefits of containerization without sacrificing usability or integration. It’s particularly valuable for users who need to work with software from multiple Linux distributions or maintain clean separation between different development environments while keeping everything easily accessible and performant.

Below you can find some useful commands for Distrobox:

Installation

Install Distrobox

# Via curl (recommended)
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh

# Via wget
wget -qO- https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh

# Install to custom location
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --prefix ~/.local

# Uninstall
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/uninstall | sh

Prerequisites

# Install Podman (preferred)
sudo dnf install podman         # Fedora/RHEL
sudo apt install podman         # Ubuntu/Debian
sudo pacman -S podman          # Arch

# Or Docker
sudo apt install docker.io      # Ubuntu/Debian
sudo dnf install docker         # Fedora

Container Management

Create Containers

# Basic container creation
distrobox create --name mybox --image ubuntu:22.04

# With custom home directory
distrobox create --name devbox --image fedora:38 --home ~/devbox

# With additional volumes
distrobox create --name workbox --image archlinux --volume /mnt/data:/data

# With specific user
distrobox create --name testbox --image debian:12 --user myuser

# With init system
distrobox create --name systembox --image ubuntu:22.04 --init

# With pre/post init hooks
distrobox create --name hookbox --image fedora:38 --pre-init-hooks "dnf update -y"

# Clone existing container
distrobox create --name newbox --clone oldbox

Popular Base Images

# Ubuntu variants
--image ubuntu:22.04
--image ubuntu:20.04
--image ubuntu:latest

# Fedora variants
--image fedora:38
--image fedora:39
--image fedora:rawhide

# Arch Linux
--image archlinux:latest
--image archlinux/archlinux:base-devel

# Debian
--image debian:12
--image debian:bullseye
--image debian:bookworm

# openSUSE
--image opensuse/tumbleweed
--image opensuse/leap:15.5

# CentOS/RHEL-like
--image quay.io/centos/centos:stream9
--image registry.access.redhat.com/ubi8/ubi

# Alpine
--image alpine:latest
--image alpine:3.18

Container Operations

# List containers
distrobox list

# Enter container
distrobox enter mybox

# Enter as different user
distrobox enter mybox --user root

# Execute single command
distrobox enter mybox -- ls -la

# Stop container
distrobox stop mybox

# Start stopped container
distrobox start mybox

# Remove container
distrobox rm mybox

# Remove with force
distrobox rm mybox --force

Application Integration

Export Applications

# Export GUI application
distrobox-export --app firefox

# Export with custom name
distrobox-export --app firefox --extra-flags "--name CustomFirefox"

# Export command-line tool
distrobox-export --bin htop

# Export with custom path
distrobox-export --bin nvim --export-path ~/.local/bin

# Export service/daemon
distrobox-export --service nginx

# List exported apps
distrobox-export --list

# Delete exported app
distrobox-export --app firefox --delete

Desktop Integration

# Export with desktop entry
distrobox-export --app code --extra-flags "--desktop"

# Export with custom icon
distrobox-export --app myapp --icon /path/to/icon.png

# Export with sudo wrapper
distrobox-export --bin some-tool --sudo

Configuration

Global Configuration (~/.config/distrobox/distrobox.conf)

# Default container engine
container_manager="podman"

# Default image to use
container_default_image="registry.fedoraproject.org/fedora-toolbox:38"

# Default additional flags
container_additional_flags="--userns=keep-id"

# Non-interactive mode
non_interactive="false"

# Skip compatibility checks
skip_workdir="false"

Container-Specific Configuration

# Inside container: ~/.distroboxrc
# Pre-init hooks
if [ -f /run/.containerenv ] || [ -f /.dockerenv ]; then
    # Container-specific setup
    echo "Setting up development environment..."
fi

Advanced Usage

Volume Mounting

# Mount additional directories
distrobox create --name devbox --image ubuntu:22.04 
  --volume /mnt/projects:/projects:Z 
  --volume /mnt/data:/data:ro

# Mount with SELinux context
--volume /host/path:/container/path:Z    # Private unshared label
--volume /host/path:/container/path:z    # Shared label

Network Configuration

# Use host networking (default)
distrobox create --name netbox --image fedora:38 --net host

# Custom network
distrobox create --name isolated --image alpine --net none

# Port forwarding
distrobox create --name webapp --image ubuntu:22.04 --volume /dev:/dev:rslave --additional-flags "-p 8080:8080"

Environment Variables

# Pass environment variables
distrobox create --name envbox --image fedora:38 
  --additional-flags "-e EDITOR=vim -e BROWSER=firefox"

# From file
--additional-flags "--env-file /path/to/env.list"

Custom Initialization

# Pre-init hooks (run as root)
distrobox create --name initbox --image ubuntu:22.04 
  --pre-init-hooks "apt update && apt install -y build-essential"

# Post-init hooks (run as user)
--init-hooks "pip install --user requests pandas"

Package Management Examples

Inside Containers

# Ubuntu/Debian containers
sudo apt update && sudo apt install package-name

# Fedora containers
sudo dnf install package-name

# Arch containers
sudo pacman -S package-name
# Enable AUR (if using base-devel image)
git clone https://aur.archlinux.org/yay.git && cd yay && makepkg -si

# Alpine containers
sudo apk add package-name

# openSUSE containers
sudo zypper install package-name

Development Workflows

Development Container Setup

# Node.js development
distrobox create --name nodejs --image node:18 
  --volume ~/projects:/projects

# Python development
distrobox create --name python --image python:3.11 
  --init-hooks "pip install --user poetry black flake8"

# Go development
distrobox create --name golang --image golang:1.21 
  --volume ~/go:/go

# Rust development
distrobox create --name rust --image rust:latest 
  --init-hooks "rustup component add clippy rustfmt"

Multi-Distribution Testing

# Create test environments
for distro in ubuntu:22.04 fedora:38 archlinux debian:12; do
    distrobox create --name "test-${distro%%:*}" --image "$distro"
done

# Test script across distributions
for container in test-ubuntu test-fedora test-arch test-debian; do
    distrobox enter "$container" -- ./test-script.sh
done

Troubleshooting

Common Issues

# Check container status
distrobox list
podman ps -a

# View container logs
podman logs distrobox-mybox

# Reset container
distrobox stop mybox
distrobox rm mybox
distrobox create --name mybox --image ubuntu:22.04

# Fix permissions
distrobox enter mybox -- sudo chown -R $USER:$USER /home/$USER

# Update container image
podman pull ubuntu:22.04
distrobox create --name mybox-new --image ubuntu:22.04
# Migrate data, then remove old container

Debug Mode

# Enable verbose output
DBX_VERBOSE=1 distrobox create --name debug --image fedora:38

# Container inspection
distrobox enter mybox -- cat /etc/os-release
distrobox enter mybox -- id
distrobox enter mybox -- mount | grep home

Tips and Best Practices

Organization

# Use descriptive names
distrobox create --name web-dev-ubuntu --image ubuntu:22.04
distrobox create --name data-science-fedora --image fedora:38

# Group related containers
distrobox create --name proj-frontend --image node:18
distrobox create --name proj-backend --image python:3.11
distrobox create --name proj-database --image postgres:15

Performance Optimization

# Use local images when possible
podman pull ubuntu:22.04
distrobox create --name fast --image localhost/ubuntu:22.04

# Minimize container size
distrobox create --name minimal --image alpine:latest

# Share package cache
distrobox create --name cached --image fedora:38 
  --volume ~/.cache/dnf:/var/cache/dnf

Backup and Migration

# Export container as image
podman commit distrobox-mybox mybox-backup

# Save container image
podman save mybox-backup -o mybox-backup.tar

# Load on another system
podman load -i mybox-backup.tar
distrobox create --name restored --image mybox-backup

Useful Aliases and Functions

Shell Aliases

# Add to ~/.bashrc or ~/.zshrc
alias dbc='distrobox create'
alias dbe='distrobox enter'
alias dbl='distrobox list'
alias dbr='distrobox rm'
alias dbs='distrobox stop'

# Quick container entry
alias ubuntu='distrobox enter ubuntu'
alias fedora='distrobox enter fedora'
alias arch='distrobox enter arch'

# Container with specific commands
function dbexec() {
    distrobox enter "$1" -- "${@:2}"
}

Useful Scripts

#!/bin/bash
# Quick setup script for new containers
setup_container() {
    local name="$1"
    local image="$2"

    distrobox create --name "$name" --image "$image" 
        --init-hooks "echo 'Container ready!'"

    echo "Container $name created successfully!"
    echo "Enter with: distrobox enter $name"
}

# Usage: setup_container mydev ubuntu:22.04

Integration Examples

IDE Integration

# VS Code in container
distrobox enter devbox -- code /projects/myproject

# Export VS Code for seamless use
distrobox-export --app code

# Vim/Neovim with plugins
distrobox create --name vim --image archlinux 
  --init-hooks "pacman -S neovim git"

GUI Applications

# Graphics applications
distrobox enter artbox -- gimp
distrobox enter artbox -- blender

# Export for desktop use
distrobox-export --app gimp
distrobox-export --app firefox

This cheatsheet covers the most common Distrobox operations and use cases. Refer to distrobox --help and individual command help for more detailed options.