Use any Linux distribution inside your terminal. Enable both backward and forward
compatibility with software and freedom to use whatever distribution you’re more
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.
- Useful tips
- Execute complex commands directly from distrobox-enter
- Create a distrobox with a custom HOME directory
- Mount additional volumes in a distrobox
- Use a different shell than the host
- Duplicate an existing distrobox
- Export to the host
- Execute commands on the host
- Enable SSH X-Forwarding when SSH-ing in a distrobox
- Using podman or docker inside a distrobox
- Using init system inside a distrobox
- Using distrobox as main cli
- Using a different architecture
- Slow creation on podman and image size getting bigger with distrobox-create
- Container save and restore
- Check used resources
- Build a Gentoo distrobox container
- Build a Dedicated distrobox container
- Featured Articles
- Run Distrobox on Fedora Linux – Fedora Magazine
- DistroBox – Run Any Linux Distribution Inside Linux Terminal – TecMint
- Distrobox: Try Multiple Linux Distributions via the Terminal – It’s FOSS
- Distrobox – How to quickly deploy a Linux distribution with GUI applications via a container
- Using Distrobox To Augment The Package Selection On Clear Linux – Phoronix
- Benchmark: benefits of Clear Linux containers (distrobox) – Phoronix
- Distrobox – A great item in the Linux toolbelt – phmurphy’s blog
- Distrobox: Run (pretty much) any Linux distro under almost any other – TheRegister
- Day-to-day differences between Fedora Silverblue and Ubuntu – castrojo’s blog
- Distrobox is Awesome – Running Window Manager and Desktop environments using Distrobox
- Japanese input on Clear Linux with Mozc via Ubuntu container with Distrobox
- MID (MaXX Interactive Desktop) on Clear Linux via Ubuntu container with Distrobox
- Running Other Linux Distros with Distrobox on Fedora Linux – bandithijo’s blog
- Talks and Videos
- Linux App Summit 2022 – Distrobox: Run Any App On Any Distro – BoF
- Opensource Summit 2022 – Distrobox: Run Any App On Any Distro
- A “Box” Full of Tools and Distros – Dario Faggioli @ OpenSUSE Conference 2022
- Podman Community Meeting October 4, 2022
- Distrobox opens the Steam Deck to a whole new world (GUIDE) – GamingOnLinux
What it does
Simply put it’s a fancy wrapper around
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
instead of calling the single files.
See it in action
- 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
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
~$ 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
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.
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
Create a new distrobox:
distrobox create -n test
Enter created distrobox:
distrobox enter test
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:
Stop a running distrobox:
distrobox stop test
Remove a distrobox
distrobox rm test
Manifest files can be used to declare a set of distroboxes and use
distrobox-assemble to create/destroy them in batch.
Take this example
[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.
Configuration files can be placed in the following paths, from the least important
to the most important:
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" non_interactive="1" skip_workdir="0"
Alternatively it is possible to specify preferences using ENV variables:
Distrobox is packaged in the following distributions, if your distribution is
on this list, you can refer to your repos for installation:
You can also follow the guide to install in a rootless manner
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
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
Remember to add prefix-path-you-choose/bin to your PATH, to make it work.
Alternatively you can clone the project using
git clone or using the latest
Enter the directory and run
./install, by default it will attempt to install
~/.local but if you run the script as root, it will default to
You can specify a custom directory with the
./install --prefix ~/.distrobox.
Prefix explained: main distrobox files get installed to
the manpages get installed to
Check the Host Distros compatibility list for
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
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.
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
enter the directory and run
./uninstall, by default it will assume the install
/usr/local if ran as root or
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