mirror of
https://github.com/89luca89/distrobox.git
synced 2026-08-19 01:14:49 -05:00
417 lines
20 KiB
Markdown
417 lines
20 KiB
Markdown
<img src="assets/splash.svg" style="border-radius:12px">
|
||
|
||
# Distrobox
|
||
|
||
<sub>previous logo credits [j4ckr3d](https://github.com/j4ckr3d)
|
||
current logo credits [David Lapshin](https://github.com/daudix)<sub>
|
||
|
||
[](https://github.com/89luca89/distrobox/actions/workflows/main.yml)
|
||
[](https://github.com/89luca89/distrobox/actions/workflows/compatibility.yml)
|
||
[](../COPYING.md)
|
||
[](https://github.com/89luca89/distrobox/releases/latest)
|
||
[](https://repology.org/project/distrobox/versions)
|
||
[](https://github.com/89luca89/distrobox/issues?q=is%3Aissue+is%3Aopen+label%3Abug+-label%3Await-on-user)
|
||
|
||
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`](https://github.com/89luca89/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](https://distrobox.it/#distrobox) -
|
||
[Matrix Room](https://matrix.to/#/%23distrobox:matrix.org) -
|
||
[Telegram Group](https://t.me/distrobox_chat_new)
|
||
|
||
---
|
||
|
||
|
||
|
||
---
|
||
|
||
> [!WARNING]
|
||
> Documentation on GitHub strictly refers to the code in the main branch. For the official documentation
|
||
> Head over [https://distrobox.it](https://distrobox.it)
|
||
|
||
- [Distrobox](#distrobox)
|
||
- [What it does](#what-it-does)
|
||
- [See it in action](#see-it-in-action)
|
||
- [Why?](#why)
|
||
- [Aims](#aims)
|
||
- [Security implications](#security-implications)
|
||
- [Quick Start](#quick-start)
|
||
- [Assemble Distrobox](#assemble-distrobox)
|
||
- [Configure Distrobox](#configure-distrobox)
|
||
- [Installation](#installation)
|
||
- [Building from source](#building-from-source)
|
||
- [Dependencies](#dependencies)
|
||
- [Install Podman without root](compatibility.md#install-podman-in-a-static-manner)
|
||
- [Compatibility](compatibility.md)
|
||
- [Supported container managers](compatibility.md#supported-container-managers)
|
||
- [Host Distros](compatibility.md#host-distros)
|
||
- [Install on the Steamdeck](posts/steamdeck_guide.md)
|
||
- [Containers Distros](compatibility.md#containers-distros)
|
||
- [Usage](usage/usage.md)
|
||
- [Outside the distrobox](usage/usage.md#outside-the-distrobox)
|
||
- [distrobox-assemble](usage/distrobox-assemble.md)
|
||
- [distrobox-create](usage/distrobox-create.md)
|
||
- [distrobox-enter](usage/distrobox-enter.md)
|
||
- [distrobox-ephemeral](usage/distrobox-ephemeral.md)
|
||
- [distrobox-generate-entry](usage/distrobox-generate-entry.md)
|
||
- [distrobox-list](usage/distrobox-list.md)
|
||
- [distrobox-rm](usage/distrobox-rm.md)
|
||
- [distrobox-stop](usage/distrobox-stop.md)
|
||
- [distrobox-upgrade](usage/distrobox-upgrade.md)
|
||
- [Inside the distrobox](usage/usage.md#inside-the-distrobox)
|
||
- [distrobox-export](usage/distrobox-export.md)
|
||
- [distrobox-host-exec](usage/distrobox-host-exec.md)
|
||
- [distrobox-init](usage/distrobox-init.md)
|
||
- [Configure distrobox](#configure-distrobox)
|
||
- [Useful tips](useful_tips.md)
|
||
- [Launch a distrobox from your applications list](useful_tips.md#launch-a-distrobox-from-your-applications-list)
|
||
- [Create a distrobox with a custom HOME directory](useful_tips.md#create-a-distrobox-with-a-custom-home-directory)
|
||
- [Mount additional volumes in a distrobox](useful_tips.md#mount-additional-volumes-in-a-distrobox)
|
||
- [Use a different shell than the host](useful_tips.md#use-a-different-shell-than-the-host)
|
||
- [Run the container with real root](useful_tips.md#run-the-container-with-real-root)
|
||
- [Run Debian/Ubuntu container behind proxy](useful_tips.md#run-debianubuntu-container-behind-proxy)
|
||
- [Using a command other than sudo to run a rootful container](useful_tips.md#using-a-command-other-than-sudo-to-run-a-rootful-container)
|
||
- [Duplicate an existing distrobox](useful_tips.md#duplicate-an-existing-distrobox)
|
||
- [Export to the host](useful_tips.md#export-to-the-host)
|
||
- [Execute commands on the host](useful_tips.md#execute-commands-on-the-host)
|
||
- [Resolve "Error cannot open display: :0"](useful_tips.md#resolve-error-cannot-open-display-0)
|
||
- [Enable SSH X-Forwarding when SSH-ing in a distrobox](useful_tips.md#enable-ssh-x-forwarding-when-ssh-ing-in-a-distrobox)
|
||
- [Using init system inside a distrobox](useful_tips.md#using-init-system-inside-a-distrobox)
|
||
- [Using Docker inside a Distrobox](useful_tips.md#using-docker-inside-a-distrobox)
|
||
- [Using Podman inside a Distrobox](useful_tips.md#using-podman-inside-a-distrobox)
|
||
- [Using LXC inside a Distrobox](useful_tips.md#using-lxc-inside-a-distrobox)
|
||
- [Using Waydroid inside a Distrobox](useful_tips.md#using-waydroid-inside-a-distrobox)
|
||
- [Manual Installation](useful_tips.md#manual-installation)
|
||
- [Automated Installation](useful_tips.md#automated-installation)
|
||
- [Using host's Podman or Docker inside a Distrobox](useful_tips.md#using-hosts-podman-or-docker-inside-a-distrobox)
|
||
- [Using distrobox as main cli](useful_tips.md#using-distrobox-as-main-cli)
|
||
- [Using a different architecture](useful_tips.md#using-a-different-architecture)
|
||
- [Using the GPU inside the container](useful_tips.md#using-the-gpu-inside-the-container)
|
||
- [Using nvidia-container-toolkit](useful_tips.md#using-nvidia-container-toolkit)
|
||
- [Slow creation on podman and image size getting bigger with distrobox create](useful_tips.md#slow-creation-on-podman-and-image-size-getting-bigger-with-distrobox-create)
|
||
- [Container save and restore](useful_tips.md#container-save-and-restore)
|
||
- [Check used resources](useful_tips.md#check-used-resources)
|
||
- [Pre-installing additional package repositories](useful_tips.md#pre-installing-additional-package-repositories)
|
||
- [Apply resource limitation on the fly](useful_tips.md#apply-resource-limitation-on-the-fly)
|
||
- [Posts](posts/posts.md)
|
||
- [Announcing the next generation of Distrobox](posts/announcing_distrobox_next.md)
|
||
- [Distrobox Next architecture](posts/distrobox_next_architecture.md)
|
||
- [Create a dedicated distrobox container](posts/distrobox_custom.md)
|
||
- [Execute a command on the Host](posts/execute_commands_on_host.md)
|
||
- [Install Podman in HOME](posts/install_podman_static.md)
|
||
- [Install Lilipod in HOME](posts/install_lilipod_static.md)
|
||
- [Install on Steamdeck](posts/steamdeck_guide.md)
|
||
- [Integrate VSCode and Distrobox](posts/integrate_vscode_distrobox.md)
|
||
- [Run Libvirt using distrobox](posts/run_libvirt_in_distrobox.md)
|
||
- [Run latest GNOME and KDE Plasma using distrobox](posts/run_latest_gnome_kde_hyprland_on_distrobox.md)
|
||
- [Featured Articles](featured_articles.md)
|
||
- [Articles](featured_articles.md#articles)
|
||
- [Run Distrobox on Fedora Linux - Fedora Magazine](https://fedoramagazine.org/run-distrobox-on-fedora-linux/)
|
||
- [DistroBox – Run Any Linux Distribution Inside Linux Terminal - TecMint](https://www.tecmint.com/distrobox-run-any-linux-distribution/)
|
||
- [Distrobox: Try Multiple Linux Distributions via the Terminal - It's FOSS](https://itsfoss.com/distrobox/)
|
||
- [Distrobox - How to quickly deploy a Linux distribution with GUI applications via a container](https://www.techrepublic.com/article/how-to-quickly-deploy-a-linux-distribution-with-gui-applications-via-a-container/)
|
||
- [Using Distrobox To Augment The Package Selection On Clear Linux - Phoronix](https://www.phoronix.com/scan.php?page=news_item&px=Distrobox-Clear-Linux)
|
||
- [Benchmark: benefits of Clear Linux containers (distrobox) - Phoronix](https://www.phoronix.com/forums/forum/phoronix/latest-phoronix-articles/1305326-clear-linux-container-performance-continues-showing-sizable-gains)
|
||
- [Distrobox - A great item in the Linux toolbelt - phmurphy's blog](https://phmurphy.com/posts/distrobox-toolbelt/)
|
||
- [Distrobox: Run (pretty much) any Linux distro under almost any other - TheRegister](https://www.theregister.com/2022/05/31/distrobox_130_released/)
|
||
- [Day-to-day differences between Fedora Silverblue and Ubuntu - castrojo's blog](https://www.ypsidanger.com/day-to-day-advantages-of-fedora-silverblue/)
|
||
- [Distrobox is Awesome - Running Window Manager and Desktop environments using Distrobox](https://cloudyday.tech.blog/2022/05/14/distrobox-is-awesome/)
|
||
- [Japanese input on Clear Linux with Mozc via Ubuntu container with Distrobox](https://impsbl.hatenablog.jp/entry/JapaneseInputOnClearLinuxWithMozc_en)
|
||
- [MID (MaXX Interactive Desktop) on Clear Linux via Ubuntu container with Distrobox](https://impsbl.hatenablog.jp/entry/MIDonClearLinuxWithDistrobox_en)
|
||
- [Running Other Linux Distros with Distrobox on Fedora Linux - bandithijo's blog](featured_articles.md)
|
||
- [Talks and Videos](featured_articles.md#talks)
|
||
- [Linux App Summit 2022 - Distrobox: Run Any App On Any Distro - BoF](https://github.com/89luca89/distrobox/files/8598433/distrobox-las-talk.pdf)
|
||
- [Opensource Summit 2022 - Distrobox: Run Any App On Any Distro](https://www.youtube.com/watch?v=eM1p47tow4o)
|
||
- [A "Box" Full of Tools and Distros - Dario Faggioli @ OpenSUSE Conference 2022](https://www.youtube.com/watch?v=_RzARte80SQ)
|
||
- [Podman Community Meeting October 4, 2022](https://www.youtube.com/watch?v=JNijOHL4_Ko)
|
||
- [Distrobox opens the Steam Deck to a whole new world (GUIDE) - GamingOnLinux](https://www.youtube.com/watch?v=kkkyNA31KOA)
|
||
- [CERN - Containerization as a means of extending the lifetime of HDL development tools](https://cdsweb.cern.ch/record/2859962?ln=ja)
|
||
- [How to Code with Distrobox on the Steam Deck](https://www.youtube.com/watch?v=qic7lmACqPo)
|
||
- [Why you should be running the MicroOS Desktop](https://www.youtube.com/watch?v=lKYLF1tA4Ik)
|
||
- [Podcasts](featured_articles.md#podcasts)
|
||
|
||
---
|
||
|
||
## 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](https://github.com/opencontainers/image-spec).
|
||
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` – create and destroy containers based on a config file
|
||
- `distrobox-create` – create a container
|
||
- `distrobox-enter` – enter a container
|
||
- `distrobox-ephemeral` – create a temporal container, destroy it when exiting the shell
|
||
- `distrobox-list` – list containers created with distrobox
|
||
- `distrobox-rm` – delete a container created with distrobox
|
||
- `distrobox-stop` – stop a running container created with distrobox
|
||
- `distrobox-upgrade` – upgrade one or more running containers created with distrobox at once
|
||
- `distrobox-generate-entry` – create an entry of a created container in the applications list
|
||
- `distrobox-init` – entry point of the container (not meant to be used manually)
|
||
- `distrobox-export` – use inside the container,
|
||
export apps and services from the container to the host
|
||
- `distrobox-host-exec` – 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](usage/usage.md) and [see some handy tips on how to use it](useful_tips.md).
|
||
|
||
### See it in action
|
||
|
||
Thanks to [castrojo](https://github.com/castrojo), you can see Distrobox in
|
||
action in this explanatory video on his setup with Distrobox, Toolbx,
|
||
Fedora Silverblue for the [uBlue](https://github.com/ublue-os) project
|
||
(check it out!)
|
||
|
||
[](https://www.youtube.com/watch?v=Q2PrISAOtbY)
|
||
|
||
## Why
|
||
|
||
- Provide a mutable environment on an immutable OS, like [ChromeOS, Endless OS,
|
||
Fedora Atomic Desktops (e.g. Silverblue), OpenSUSE Aeon/Kalpa, Vanilla OS](compatibility.md#host-distros), or [SteamOS3](posts/steamdeck_guide.md)
|
||
- 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](compatibility.md#host-distros) and container's distro [HERE](compatibility.md#containers-distros).
|
||
|
||
### Aims
|
||
|
||
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](compatibility.md#supported-container-managers) 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:
|
||
|
||
```console
|
||
~$ 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](https://github.com/89luca89/distrobox/issues/28).
|
||
|
||
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](https://github.com/Gerharddc/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](https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#host-distros),
|
||
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](usage/usage.md)
|
||
and check a [comprehensive list of useful tips HERE](useful_tips.md).
|
||
|
||
# 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](usage/distrobox-assemble.md)
|
||
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
|
||
|
||
You can specify inside distrobox configurations and distrobox-specific Environment
|
||
variables.
|
||
|
||
Example configuration file:
|
||
|
||
```conf
|
||
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:
|
||
|
||
- 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:
|
||
|
||
[](https://repology.org/project/distrobox/versions)
|
||
|
||
Thanks to the maintainers for their work: [M0Rf30](https://github.com/M0Rf30),
|
||
[alcir](https://github.com/alcir), [dfaggioli](https://github.com/dfaggioli),
|
||
[AtilaSaraiva](https://github.com/AtilaSaraiva), [michel-slm](https://github.com/michel-slm)
|
||
|
||
## Building from source
|
||
|
||
To build distrobox from source, you need [Go](https://go.dev/) >= 1.25 and `make`.
|
||
|
||
Clone the repository and build:
|
||
|
||
```sh
|
||
git clone https://github.com/89luca89/distrobox.git
|
||
cd distrobox
|
||
make build
|
||
```
|
||
|
||
Then install:
|
||
|
||
```sh
|
||
sudo make install
|
||
```
|
||
|
||
This installs the `distrobox` binary to `/usr/local/bin` by default.
|
||
For a local install without sudo:
|
||
|
||
```sh
|
||
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.
|
||
|
||
---
|
||
|
||
Check the [Host Distros](compatibility.md#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`](https://github.com/89luca89/lilipod).
|
||
|
||
Please look in the [Compatibility Table](compatibility.md#host-distros) for your
|
||
distribution notes.
|
||
|
||
There are ways to install
|
||
[Podman without root privileges and in home](compatibility.md#install-podman-in-a-static-manner). Or
|
||
[Lilipod without root privileges and in home](compatibility.md#install-lilipod-in-a-static-manner).
|
||
This should play well with completely sudoless setups and with devices like the Steam Deck (SteamOS).
|
||
|
||
---
|
||
|
||
---
|
||
|
||
|
||
|
||
<sub>This artwork uses [Cardboard Box](https://skfb.ly/6Wq6q) model by [J0Y](https://sketchfab.com/lloydrostek)
|
||
licensed under [Creative Commons Attribution 4.0](http://creativecommons.org/licenses/by/4.0)
|
||
This artwork uses [GTK Loop Animation](https://github.com/gnome-design-team/gnome-mockups/blob/master/gtk/loop6.blend)
|
||
by [GNOME Project](https://www.gnome.org)
|
||
licensed under [Creative Commons Attribution-ShareAlike 3.0](https://creativecommons.org/licenses/by-sa/3.0)
|
||
as a pre-configured scene<sub>
|