distrobox-create

Create a Distrobox container using the Ubuntu image

$ distrobox-create [container_name] [[-i|--image]] [ubuntu:latest]

$ distrobox-create [[-c|--clone]] [container_name] [cloned_container_name]

distrobox-create [options...] <image> [<name>]

--name, -n <name>
    Specify custom container name (defaults to image distro name)

--image, -i <image>
    Image to use (e.g., ubuntu:22.04); overrides image arg if provided

--distro <distro>
    Force distro name (auto-detected from image)

--arch <arch>
    Target architecture (e.g., amd64)

--home <path>
    Custom home directory path inside container

--user <user>
    Username in container (defaults to host user)

--uid <uid>
    User ID in container

--gid <gid>
    Group ID in container

--root, -r
    Create container as root user

--additional-packages <pkgs>
    Packages to install during init (comma/space separated)

--additional-flags <flags>
    Extra flags for container runtime (Podman/Docker)

--nvidia
    Enable Nvidia GPU support

--gpu
    Enable generic GPU access

--rocm
    Enable AMD ROCm support

--host-display
    Share host display server

--host-fontconfig
    Share host fonts

--host-pulseaudio
    Share host audio

--host-gtk-theme
    Share host GTK themes

--host-ssh-agent
    Share host SSH agent

--host-dconf
    Share host dconf settings

--host-cups
    Share host printing

--host-udev
    Share host udev events

--init, -I <script>
    Custom init script

--pre-init-hooks <hooks>
    Hooks before init (semicolon separated)

--post-create-hook <hook>
    Script after container creation

--yes, -y
    Non-interactive mode, auto-confirm

--verbose, -v
    Verbose output

--quiet, -q
    Suppress output

--dry-run
    Simulate without creating

--skip-updates
    Skip distro package updates on init

--help
    Show help

Distrobox-create is a command-line tool from the Distrobox project that enables users to create and initialize lightweight, containerized environments for various Linux distributions. Using container technologies like Podman or Docker, it pulls a specified distribution image (e.g., ubuntu:22.04 or fedora:39) and configures the container to integrate seamlessly with the host system.

This integration includes sharing the user's home directory, display server (X11/Wayland), audio, fonts, themes, and hardware access (e.g., GPU, ROCm). The resulting container acts like a native distro, allowing apps to run with host-native performance and permissions. It supports custom users, additional package installations during creation, and hooks for pre/post scripts.

Ideal for developers testing software across distros without dual-booting or VMs, it preserves host package management while isolating the container's. Containers are manageable via standard tools and can be exported/imported for portability.

Requires Podman or Docker. Images must be accessible via registries. Host/container UID mismatches may cause permission issues. GPU/ROCm options experimental on some setups. Not for production servers.

distrobox create --name my-ubuntu ubuntu:22.04
Creates Ubuntu 22.04 container named 'my-ubuntu'. Use distrobox enter my-ubuntu to access.

distrobox create fedora:39 --nvidia --additional-packages vim htop
Fedora with Nvidia and extra packages.

Distrobox launched in 2021 by Luca Wehr (89luca89) as an evolution of tools like toolbox/lpodman. Gained popularity for immutable distro users (e.g., Silverblue, SteamOS). Actively maintained with v1.6+ adding ROCm/Nvidia support; used in thousands of installs via Flathub/AUR.

distrobox(1), distrobox-enter(1), distrobox-export(1), podman-run(1), docker-run(1)