_{previous logo credits j4ckr3d

current logo credits David Lapshin}

Distrobox

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 or docker 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

What it does

Simply put it's a fancy wrapper around podman or docker to create and start containers 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 but in a simplified way using POSIX sh and aiming at broader compatibility.

All the props go to them as they had the great idea to implement this stuff.

It is divided into 12 commands:

distrobox-assemble - creates and destroy containers based on a config file
distrobox-create - creates the container
distrobox-enter - to enter the container
distrobox-ephemeral - create a temporal container, destroy it when exiting the shell
distrobox-list - to list containers created with distrobox
distrobox-rm - to delete a container created with distrobox
distrobox-stop - to stop a running container created with distrobox
distrobox-upgrade - to upgrade one or more running containers created with distrobox at once
distrobox-generate-entry - to create an entry of a created container in the applications list
distrobox-init - the entrypoint of the container (not meant to be used manually)
distrobox-export - it is meant to be used inside the container, useful to export apps and services from the container to the host
distrobox-host-exec - to run commands/programs from the host, while inside of the container

It also includes a little wrapper to launch commands with distrobox COMMAND instead of calling the single files.

Please check the usage docs here 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 Endless OS, Fedora Silverblue, OpenSUSE MicroOS or SteamOS3
Provide a locally privileged environment for sudoless setups (eg. company-provided laptops, security reasons, etc...)
To mix and match a stable base system (eg. Debian Stable, Ubuntu LTS, RedHat) with a bleeding-edge environment for development or gaming (eg. Arch, OpenSUSE Tumbleweed or Fedora with latest Mesa)
Leverage high abundance of curated distro images for docker/podman to manage multiple environments

Refer to the compatibility list for an overview of supported host's distro HERE and container's distro HERE.

Aims

This project aims to bring any distro userland to any other distro supporting podman or docker. It has been written in POSIX sh to be as portable as possible and not have problems with dependencies and glibc version's compatibility.

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 is not the main aim 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 drives 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 with the --root/-r flag, the containers will run as root, so root inside the rootful container can modify system stuff outside the container, if you have security concern for this, use podman 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 in the works to implement some sort of decoupling with the host, as discussed here: #28 Sandboxed mode

Basic usage

Create a new distrobox:

distrobox create -n test

Enter created distrobox:

distrobox enter test

Add various distroboxes, eg Ubuntu 20.04:

distrobox create -i ubuntu:20.04

Execute a command in a distrobox:

distrobox enter test -- command-to-execute

Upgrade all distroboxes at once:

distrobox upgrade --all

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.

Take this example distrobox-example.ini file:

[alpine3]
additional_packages=git vim tmux nodejs
home=/tmp/home
image=alpine:latest

[debian5]
additional_packages=git vim tmux nodejs
home=/tmp/home
image=debian:latest
init=false
init_hooks="touch /init-normal"

[opensuse]
additional_packages=git vim tmux nodejs
home=/tmp/home
image=opensuse/tumbleweed:latest
init=true
init_hooks="touch /init-normal"
pre_init_hooks="touch /pre-init"
pull=true

Using the following command:

distrobox-assemble create -f ./distrobox-example.ini

We can create all the distroboxes at once, configured as declared in the manifest file. We can also recreate them from scratch using:

distrobox-assemble create --replace -f ./distrobox-example.ini

And finally destroy all of them at once with

distrobox-assemble rm -f ./distrobox-example.ini

Head over the usage docs of distrobox-assemble for a more detailed guide.

Configure Distrobox

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

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"
non_interactive="1"
skip_workdir="0"

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

You can also follow the guide to install in a rootless manner

Alternative methods

Here is a list of alternative ways to install distrobox

Curl or Wget

If you like to live your life dangerously, or you want the latest release, you can trust me and simply run this in your terminal:

curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sudo sh
# or using wget
wget -qO- https://raw.githubusercontent.com/89luca89/distrobox/main/install | sudo sh

or if you want to select a custom directory to install without sudo:

curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --prefix ~/.local
# or using wget
wget -qO- https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --prefix ~/.local

If you want to install the last development version, directly from last commit on git, you can use:

curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sudo sh -s -- --next
# or using wget
wget -qO- https://raw.githubusercontent.com/89luca89/distrobox/main/install | sudo sh -s -- --next

or:

curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --next --prefix ~/.local
# or using wget
wget -qO- https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --next --prefix ~/.local

Warning Remember to add prefix-path-you-choose/bin to your PATH, to make it work.

Git

Alternatively you can clone the project using git clone or using the latest release HERE.

Enter the directory and run ./install, by default it will attempt to install in ~/.local but if you run the script as root, it will default to /usr/local. You can specify a custom directory with the --prefix flag such as ./install --prefix ~/.distrobox.

Prefix explained: main distrobox files get installed to ${prefix}/bin whereas the manpages get installed to ${prefix}/share/man.

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 or docker.

Please look in the Compatibility Table for your distribution notes.

There are ways to install Podman without root privileges and in home. This should play well with completely sudoless setups and with devices like the Steam Deck.

Uninstallation

If you installed distrobox using the install script in the default install directory use this:

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

or if you specified a custom path:

curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/uninstall | sh -s -- --prefix ~/.local

Else if cloned the project using git clone or using the latest archive release from HERE,

enter the directory and run ./uninstall, by default it will assume the install directory was /usr/local if ran as root or ~/.local, you can specify another directory if needed with ./uninstall --prefix ~/.local

_{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}

sandorex/distrobox