Distrobox
previous logo credits j4ckr3d
current logo credits David Lapshin
Use any Linux distribution inside your terminal. Enable both backward and forward
compatibility with software and freedom to use whatever distribution you’re more
comfortable with.
Distrobox uses podman, docker or
lilipod to create containers using the Linux distribution
of your choice.
The created container will be tightly integrated with the host, allowing sharing
of the HOME directory of the user, external storage, external USB devices and
graphical apps (X11/Wayland), and audio.
Documentation -
Matrix Room -
Telegram Group
[!WARNING]
Documentation on GitHub strictly refers to the code in the main branch. For the official documentation
Head over https://distrobox.it
What it does
Simply put it's a fancy wrapper around podman, docker, or lilipod to create and start
containers which are highly integrated with the hosts.
The distrobox environment is based on an OCI image.
This image is used to create a container that seamlessly integrates with the
rest of the operating system by providing access to the user's home directory,
the Wayland and X11 sockets, networking, removable devices (like USB sticks),
systemd journal, SSH agent, D-Bus,
ulimits, /dev and the udev database, etc...
It implements the same concepts introduced by https://github.com/containers/toolbox,
keeping integration and broad host compatibility as primary goals.
All the props go to them as they had the great idea to implement this stuff.
distrobox is shipped as a single binary providing the following subcommands:
distrobox assemble – create and destroy containers based on a config filedistrobox create – create a containerdistrobox enter – enter a containerdistrobox ephemeral – create a temporary container, destroy it when exiting the shelldistrobox list (alias: ls) – list containers created with distroboxdistrobox rm – delete a container created with distroboxdistrobox stop – stop a running container created with distroboxdistrobox upgrade – upgrade one or more containers created with distrobox at oncedistrobox generate-entry – create an entry of a created container in the applications list
Plus three helpers that run inside the container:
distrobox-init – container entrypoint (not meant to be invoked manually)distrobox-export – export apps and services from the container to the hostdistrobox-host-exec – run commands/programs from the host while inside the container
Please check the usage docs and see some handy tips on how to use it.
See it in action
Thanks to castrojo, you can see Distrobox in
action in this explanatory video on his setup with Distrobox, Toolbx,
Fedora Silverblue for the uBlue project
(check it out!)
Why
- Provide a mutable environment on an immutable OS, like ChromeOS, Endless OS,
Fedora Atomic Desktops (e.g. Silverblue), OpenSUSE Aeon/Kalpa, Vanilla OS, or SteamOS3
- Provide a locally privileged environment for sudoless setups
(e.g. company-provided laptops, security reasons, etc...)
- To mix and match a stable base system (e.g. Debian Stable, Ubuntu LTS, Red Hat)
with a bleeding-edge environment for development or gaming
(e.g. Arch, OpenSUSE Tumbleweed, or Fedora with the latest Mesa)
- Leverage a high abundance of curated distro images for
docker/podman to
manage multiple environments.
Refer to the compatibility list for an overview of the supported host distros
HERE and container's distro HERE.
Aims
This project aims to bring any distro userland to any other distro
supporting podman, docker, or lilipod.
It is implemented as a single statically-linked Go binary, while the in-container
helpers remain POSIX shell so they keep working on any distro the binary can run.
Refer HERE for a list of
supported container managers and minimum supported versions.
It also aims to enter the container as fast as possible, every millisecond
adds up if you use the container as your default environment for your terminal:
These are some sample results of distrobox enter on the same container on my
weak laptop:
~$ hyperfine --warmup 3 --runs 100 "distrobox enter bench -- whoami"
Benchmark 1: distrobox enter bench -- whoami
Time (mean ± σ): 395.6 ms ± 10.5 ms [User: 167.4 ms, System: 62.4 ms]
Range (min … max): 297.3 ms … 408.9 ms 100 runs
Security implications
Isolation and sandboxing are not the main aims of the project, on the contrary
it aims to tightly integrate the container with the host.
The container will have complete access to your home, pen drive, and so on,
so do not expect it to be highly sandboxed like a plain
docker/podman container or a Flatpak.
⚠️ BE CAREFUL:⚠️ if you use docker, or you use podman/lilipod with the --root/-r flag,
the containers will run as root, so root inside the rootful container can modify
system stuff outside the container,
Be also aware that In rootful mode, you'll be asked to set up the user's password, this will
ensure at least that the container is not a passwordless gate to root,
but if you have security concerns for this, use podman or lilipod that runs in rootless mode.
Rootless docker is still not working as intended and will be included in the future
when it will be complete.
That said, it is useful to read the discussion about decoupling with the host,
available here: #28 Sandboxed mode.
If you are looking for something similar to Distrobox but with sandboxing capabilities,
there are other options to consider which do prioritise isolation such as Litterbox.
Quick Start
Create a new distrobox:
distrobox create -n test
Create a new distrobox with Systemd (acts similar to an LXC):
distrobox create --name test --init --image debian:latest --additional-packages "systemd libpam-systemd pipewire-audio-client-libraries"
Enter created distrobox:
distrobox enter test
Add one with a different distribution,
e.g. Ubuntu 20.04:
distrobox create -i ubuntu:20.04
Execute a command in a distrobox:
distrobox enter test -- command-to-execute
List running distroboxes:
distrobox list
Stop a running distrobox:
distrobox stop test
Remove a distrobox:
distrobox rm test
You can check HERE for more advanced usage
and check a comprehensive list of useful tips HERE.
Assemble Distrobox
Manifest files can be used to declare a set of distroboxes and use
distrobox assemble to create/destroy them in batch.
Head over the usage docs of distrobox assemble
for a more detailed guide.
Configuration files can be placed in the following paths, from the least important
to the most important:
- /usr/share/distrobox/distrobox.conf
- /usr/etc/distrobox/distrobox.conf
- /etc/distrobox/distrobox.conf
- ${HOME}/.config/distrobox/distrobox.conf
- ${HOME}/.distroboxrc
You can specify inside distrobox configurations and distrobox-specific Environment
variables.
Example configuration file:
container_always_pull="1"
container_generate_entry=0
container_manager="docker"
container_image_default="registry.opensuse.org/opensuse/toolbox:latest"
container_name_default="test-name-1"
container_user_custom_home="$HOME/.local/share/container-home-test"
container_init_hook="~/.local/distrobox/a_custom_default_init_hook.sh"
container_pre_init_hook="~/a_custom_default_pre_init_hook.sh"
container_manager_additional_flags="--env-file /path/to/file --custom-flag"
container_additional_volumes="/example:/example1 /example2:/example3:ro"
non_interactive="1"
skip_workdir="0"
PATH="$PATH:/path/to/custom/podman"
Note — configuration files are parsed as INI, not sourced as shell.
The original shell distrobox sourced distrobox.conf and ${HOME}/.distroboxrc,
so they could contain arbitrary shell (variable expansion, command substitution,
conditionals, export, etc.). The new Go implementation instead reads them as plain
key=value (INI) files. As a consequence:
- Values are taken literally:
container_user_custom_home="$HOME/..." and
PATH="$PATH:..." are not expanded — use absolute paths. The $HOME/$PATH
entries in the example above illustrate the old sourcing behavior and will not
be expanded here.
- Arbitrary shell logic in
.distroboxrc is not executed; only recognized
key=value settings take effect.
- The reference key
distrobox_sudo_program is accepted (mapped onto
sudo_program).
Alternatively, it is possible to specify preferences using ENV variables:
- DBX_CONTAINER_ALWAYS_PULL
- DBX_CONTAINER_CUSTOM_HOME
- DBX_CONTAINER_IMAGE
- DBX_CONTAINER_MANAGER
- DBX_CONTAINER_NAME
- DBX_CONTAINER_ENTRY
- DBX_NON_INTERACTIVE
- DBX_SKIP_WORKDIR
Installation
Distrobox is packaged in the following distributions, if your distribution is
on this list, you can refer to your repos for installation:
Thanks to the maintainers for their work: M0Rf30,
alcir, dfaggioli,
AtilaSaraiva, michel-slm
Building from source
To build distrobox from source, you need Go >= 1.25 and make.
Clone the repository and build:
git clone https://github.com/89luca89/distrobox.git
cd distrobox
make build
Then install:
sudo make install
This installs the distrobox binary to /usr/local/bin by default.
For a local install without sudo:
make install PREFIX=~/.local
[!WARNING]
Make sure the destination directory is in your PATH.
To uninstall, run make uninstall with the same PREFIX used during installation.
Standalone install script
The install and uninstall scripts at the repository root work without a
local checkout. They download distrobox from GitHub and deploy it to a
prefix.
The script defaults to the v1 stable line (recommended for production).
Pass --v2 to install the v2 Go release candidate instead; the script
also picks the v2 path automatically if --version points at a 2.x tag.
# v1 (default) — latest stable
curl -fsSL https://raw.githubusercontent.com/89luca89/distrobox/legacy/install | sh
# v2 — Go release candidate
curl -fsSL https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --v2
The same flags (--prefix, --version, --no-color, --verbose) work in
both modes. The companion ./uninstall script removes whatever was
installed, regardless of version.
Check the Host Distros compatibility list for
distro-specific instructions.
Dependencies
Distrobox depends on a container manager to work, you can choose to install
either podman, docker or lilipod.
Please look in the Compatibility Table for your
distribution notes.
There are ways to install
Podman without root privileges and in home. Or
Lilipod without root privileges and in home.
This should play well with completely sudoless setups and with devices like the Steam Deck (SteamOS).
This artwork uses Cardboard Box model by J0Y
licensed under Creative Commons Attribution 4.0
This artwork uses GTK Loop Animation
by GNOME Project
licensed under Creative Commons Attribution-ShareAlike 3.0
as a pre-configured scene
Distrobox 让你通过容器在终端中运行任意 Linux 发行版，同时保持环境与宿主系统紧密集成，兼顾向前和向后的软件兼容性。