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] <container-name>
distrobox-create --image <image-name> [OPTIONS] <container-name>

-h, --help
    Display a help message and exit.

-n, --name CONTAINER_NAME
    Specify the name of the container to be created.

-i, --image IMAGE
    The container image to use for the distrobox (e.g., fedora:latest, ubuntu:22.04).

-H, --hostname HOSTNAME
    Set the hostname for the container.

-V, --volume VOLUME
    Mount a volume into the container (e.g., /path/on/host:/path/in/container).

-B, --bind BIND
    Bind mount a file or directory into the container (alias for --volume).

--home HOME
    Mount the host user's home directory into the container. This is default behavior.

--init
    Use systemd-init as the container's entrypoint, useful for running services.

--unshare-groups
    Do not share the host's groups with the container.

--unshare-processes
    Do not share the host's process tree with the container.

--unshare-ipc
    Do not share the host's IPC namespace with the container.

--unshare-net
    Do not share the host's network namespace with the container.

--unshare-pid
    Do not share the host's PID namespace with the container.

--unshare-uts
    Do not share the host's UTS namespace (hostname) with the container.

--dry-run
    Perform a dry run, showing the commands that would be executed without creating the container.

--no-create
    Alias for --dry-run.

--pull
    Pull the container image even if it exists locally.

-Y, --yes
    Automatically answer yes to prompts and proceed without confirmation.

--root
    Create the distrobox as the root user. Requires sudo or root privileges.

--container-manager MANAGER
    Specify the container manager to use (podman or docker).

--additional-packages PACKAGES
    Install additional packages upon container creation (space-separated list).

--pre-init-hooks HOOKS
    Run shell commands before the container's init process starts.

--post-init-hooks HOOKS
    Run shell commands after the container's init process starts.

--clone CLONE_FROM
    Create a new distrobox by cloning an existing one.

--override-hostname
    Force override the hostname even if it conflicts with host's hostname.

--override-path PATH
    Override the default PATH environment variable inside the container.

--setup-timeout TIMEOUT
    Set a timeout for the initial setup process in seconds.

--skip-entry
    Skip the initial entry into the container after creation.

--tty
    Force TTY allocation for container processes.

--no-tty
    Disable TTY allocation for container processes.

--env VAR=VALUE
    Set an environment variable inside the container.

--install
    Installs Distrobox (used internally by the setup script).

--rm-deps
    Remove build dependencies after initial setup within the container.

--force
    Force the creation, replacing an existing container if container-name already exists.

--replace
    Alias for --force.

-v, --verbose
    Print more verbose output for debugging.

-d, --debug
    Print debug messages.

-q, --quiet
    Suppress output messages.

The distrobox-create command is a core component of the Distrobox ecosystem, designed to effortlessly create new, integrated Linux environments within containers. It leverages either Podman or Docker as its container backend, abstracting away the complexities of container management to provide a seamless user experience. The primary goal of distrobox-create is to allow users to install and run software from various Linux distributions (e.g., Fedora, Arch, Ubuntu) on their host system without affecting its integrity or needing a full virtual machine.

Unlike standard containers, a Distrobox container is specifically configured to integrate deeply with the host system. This includes sharing the user's home directory, UIDs/GIDs, X11/Wayland display, and sound system, making applications run inside the container feel almost native. When you use distrobox-create, you specify an official container image (e.g., ubuntu:latest, fedora:38), and Distrobox handles the initial setup, ensuring the environment is ready for immediate use and integration with your host desktop.

This command is ideal for developers testing software on different distributions, users who need specific packages only available in certain distros, or anyone looking to isolate applications or development environments for better system hygiene.

Requires Podman or Docker to be installed and running on the host system.
While highly integrated, some low-level hardware interactions or specific kernel modules might not function as expected due to the containerized environment.
Running graphical applications from within a Distrobox requires an active X server or Wayland compositor on the host system.
Though designed for isolation, it's still a container; certain security considerations applicable to containers apply.
Performance might be slightly less than native, especially for I/O intensive tasks, though generally negligible for typical usage.

A key feature of Distrobox is its deep integration with the host system. When a container is created, it automatically shares the user's home directory, UIDs/GIDs, X11/Wayland display, PulseAudio/PipeWire sound system, and D-Bus. This allows graphical applications and command-line tools run within the Distrobox to interact seamlessly with the host's desktop environment and peripherals, making them feel like native host applications.

Distrobox operates as a wrapper around existing container runtimes, primarily Podman and Docker. Users can specify which backend to use via the --container-manager option. Podman is often preferred for its daemon-less architecture and rootless container capabilities, aligning well with Distrobox's design principles for user-centric environments.

Beyond general isolation, distrobox-create is frequently used for:
1. Running software dependencies that conflict with the host system.
2. Developing against different Linux distributions (e.g., building .deb packages on an Arch host).
3. Testing new software versions in an isolated environment.
4. Providing a consistent development environment across different machines.

Distrobox was primarily developed by Luca Di Maio, beginning around 2021, with the aim of providing a simple, powerful, and integrated way to manage development and application environments using OCI containers. It quickly gained traction within the Linux community as a practical solution for cross-distribution compatibility and application isolation, especially for immutable operating systems like Fedora Silverblue and SteamOS. The project focuses on user-friendliness and deep integration with the host system, distinguishing itself from general-purpose container tools by its specialized focus on creating cohesive user environments.

distrobox(1), distrobox-enter(1), distrobox-list(1), distrobox-rm(1), distrobox-upgrade(1), podman(1), docker(1)