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
Simply put it’s a fancy wrapper around podman
, docker
, or lilipod
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 filedistrobox-create
- creates the containerdistrobox-enter
- to enter the containerdistrobox-ephemeral
- create a temporal container, destroy it when exiting the shelldistrobox-list
- to list containers created with distroboxdistrobox-rm
- to delete a container created with distroboxdistrobox-stop
- to stop a running container created with distroboxdistrobox-upgrade
- to upgrade one or more running containers created with distrobox at oncedistrobox-generate-entry
- to create an entry of a created container in the applications listdistrobox-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 hostdistrobox-host-exec
- to run commands/programs from the host, while inside
of the containerIt 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
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!)
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.
This project aims to bring any distro userland to any other distro
supporting podman
, docker
, or lilipod
.
It has been written in POSIX shell to be as portable as possible and it does 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
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 setup 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 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
Create a new distrobox with Systemd (acts similar to an LXC):
distrobox create --name test --init --image debian:latest --additional-packages "systemd libpam-systemd"
Enter created distrobox:
distrobox enter test
Add one with a different distribution, eg. 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
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:
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"
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:
Thanks to the maintainers for their work: M0Rf30, alcir, dfaggioli, AtilaSaraiva, michel-slm
Here is a list of alternative ways to install distrobox
.
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 the 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
Just run the curl
or wget
command again.
[!WARNING] 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
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.
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).
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