# Distrobox: run any Linux distribution inside your terminal

> Distrobox wraps podman, docker or lilipod into a set of shell commands that create a tightly integrated container from any distribution image. It is a strong fit for immutable hosts and for software that only ships for one distro family, with the caveat that it is not an isolation boundary.

**89luca89/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. Mirror available at:.

- Repository: https://github.com/89luca89/distrobox
- Website: https://distrobox.it/
- Stars: 13,010 · Forks: 544
- Language: Go
- License: GPL-3.0
- Published: 2026-09-07 · Updated: 2026-09-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/89luca89-distrobox

## The problem Distrobox solves for immutable and single-distro hosts

Linux distributions disagree about package versions, file layouts and init behaviour. If your host runs Fedora Silverblue, Kinoite, Bazzite or SteamOS, the base system is deliberately hard to modify, and a tool that only ships an Ubuntu .deb or an Arch PKGBUILD leaves you with no clean path. Distrobox's answer is to keep the host untouched and put the foreign distribution in a container instead. The README states that the created container is tightly integrated with the host, sharing the user's HOME directory, external storage, external USB devices, graphical apps over X11 and Wayland, and audio. That integration is the whole point: you get a Debian or Arch userland without a second machine, a virtual machine or a dual boot. The audience is therefore narrow but real. People on immutable desktops, Steam Deck owners, developers who need a second toolchain, and anyone who wants to test a distribution's packages without repartitioning. The project also targets the reverse direction, described as backward and forward compatibility with software, meaning the container can run applications that the host distribution has dropped or has not packaged yet. If your host distribution already has everything you need in its repositories, Distrobox adds a container manager, an image download and a layer of indirection for no benefit.

## How the container is wired to the host

The architecture is a CLI front end around an existing container runtime. The README says Distrobox uses podman, docker or lilipod to create containers using the distribution of your choice, and compatibility.md documents which container managers and which host and container distributions are supported. The Go code in cmd/ and internal/ builds a single distrobox binary, and the Makefile installs symlinks for the v1-style subcommands (assemble, create, enter, ephemeral, generate-entry, ls, list, rm, stop, upgrade) pointing at that one binary, so distrobox-create and distrobox rm both resolve to the same executable. A second set of assets, distrobox-init, distrobox-export and distrobox-host-exec, is installed from internal/inside-distrobox/assets and runs inside the container. That split explains the two documented command groups: commands you run outside the distrobox to manage containers, and commands you run inside the distrobox to export applications to the host or execute commands on the host. The integration itself is not a kernel feature. It is configuration applied at creation time, which is why the useful tips page documents mounting additional volumes, using a custom HOME directory, running with real root, using a different shell, and using the host's GPU. The container shares the host kernel, so it is a packaging and compatibility tool, not a virtual machine.

## Installing Distrobox and creating your first container

The README points to the installation section and to compatibility.md for supported host distributions; the repository also ships an install and an uninstall script at the top level, and a Makefile target for building from source. The build uses Go 1.25.3 per go.mod and produces ./bin/distrobox. If you prefer the packaged route, check compatibility.md for your distribution first, since the install method differs per host.

```bash
make build
sudo make install
```

The build step compiles the binary and the install step places it under PREFIX, which defaults to /usr/local, together with man pages, bash and zsh completions, icons, and the symlinks for the v1 subcommands. After that, distrobox should be on your PATH. The usage documentation covers the commands you run outside the distrobox, including distrobox-create, distrobox-enter, distrobox-list, distrobox-stop, distrobox-rm, distrobox-assemble, distrobox-ephemeral and distrobox-upgrade. Inside the container, distrobox-export is what puts an application or a binary onto the host's application list, and distrobox-host-exec runs a command on the host; the useful tips page has dedicated sections for exporting to the host and for executing commands on the host.

## Where Distrobox is the wrong tool

The README carries a security implications section under its aims, and it is worth reading before you treat a Distrobox container as a boundary. Because the container shares the host kernel and, by default, the user's HOME directory, it is not a sandbox. Code you run inside can read and write your home files and can reach your devices. If your goal is to run untrusted software, a virtual machine or a container configured with an explicit, restricted mount set is the appropriate tool, and Distrobox's defaults work against you. The same design creates a second class of problem: two distributions writing into one HOME directory means dotfiles and configuration caches can collide, which is why the useful tips page documents creating a distrobox with a custom HOME directory. Nested container use is another boundary. The tips page has separate sections for using Docker, Podman and LXC inside a Distrobox, and for using the host's Podman or Docker inside one, which tells you this does not work out of the box and needs deliberate configuration. Finally, the README warns that the GitHub documentation refers strictly to the code in the main branch and that the official documentation lives at distrobox.it, so a mismatch between what you read and what your installed version does is expected rather than a bug.

## Distrobox compared with Toolbox, Docker and a plain chroot

Toolbox is the closest relative and the comparison people search for most. Both create a mutable container from a distribution image and integrate it with the host user session. The difference is scope and runtime coupling: Distrobox documents podman, docker and lilipod as container managers and publishes a compatibility matrix for host and container distributions, while Toolbox is built around podman and Fedora's own image workflow. If you are on Fedora Silverblue and only need a Fedora-based toolbox, the distribution's own tool is the shorter path. If you need Arch, Ubuntu, Void or a mix, Distrobox's broader image and runtime support matters more. Against Docker, the difference is intent rather than technology. Docker is designed around isolated, reproducible services; Distrobox deliberately dissolves isolation by sharing HOME, devices, display and audio, and adds commands such as distrobox-export and distrobox-host-exec that exist precisely to cross the boundary. Using Distrobox to run a database would be a misuse; using Docker to get a working Arch userland on an immutable desktop means rebuilding the integration yourself. A plain chroot or a manually configured container can reach the same end state, but you would be hand-writing the mount, display, audio and device configuration that Distrobox generates, and you would lose the assemble, list, stop, rm and upgrade commands that make the lifecycle manageable.

## Maintenance, releases and the GPL-3.0 licence

The repository is not archived and the last push was on 2026-07-25, which is recent enough that the project is being worked on, but the release line deserves attention. The three most recent releases are 2.0.0-rc.4 on 2026-07-25, 2.0.0-rc.3 on 2026-06-29 and 2.0.0-rc.2 on 2026-04-30. All three are release candidates, so if you need a stable tag, verify which version your distribution packages rather than assuming 2.0.0 has shipped. The repository also documents a v1 subcommand set in the Makefile, and the posts directory includes an announcement of the next generation and a Distrobox Next architecture note, which suggests the 2.0 line is a structural change rather than a small increment. Upgrade cost is mostly the container manager's problem: images are pulled and containers are recreated, and the distrobox-upgrade command handles packages inside a container. Your own exported applications are the fragile part, since distrobox-export writes entries onto the host and those entries point at paths inside a container. On licensing, the project is GPL-3.0, with the licence text in COPYING.md. That governs the Distrobox code itself; the distribution images you pull carry their own licences, and the applications you run inside them carry theirs. If you redistribute a container image built with Distrobox tooling, check those terms separately. This is a description of what the repository states, not legal advice.

## Conclusion

Adopt Distrobox if you run an immutable or slow-moving host and need packages from another distribution, or if you want one environment per project without touching the base system. Do not adopt it as a sandbox: the README's security implications section says the container shares the host's kernel, HOME and devices, so treat anything you run inside as running on your machine. Before committing, check compatibility.md for your host distribution and your chosen container manager, confirm which of podman, docker or lilipod is already installed, and note that the current release line is 2.0.0-rc.4, a release candidate rather than a final version.

## FAQ

### What is Distrobox?

Distrobox is a set of commands that create containers from any Linux distribution using podman, docker or lilipod, and integrate them with the host by sharing the user's HOME directory, external storage, USB devices, graphical apps and audio.

### How do I remove a Distrobox container?

The usage documentation lists distrobox-rm for removing a container and distrobox-stop for halting one. Run distrobox rm with the container name, or distrobox stop first if it is running.

### Can I use Distrobox on Windows?

Nothing in the README or the compatibility documentation describes a Windows host. The documented hosts are Linux distributions, and the container managers it relies on are podman, docker and lilipod.

### Can I use Distrobox on Ubuntu?

Ubuntu appears in the compatibility documentation as a supported host distribution, and the README's useful tips page includes a section on running a Debian or Ubuntu container behind a proxy. Check compatibility.md for the install method that applies to your release.

### How do I install Distrobox?

The README links to an installation section and to compatibility.md for supported hosts. From source, the Makefile provides a build target that compiles ./bin/distrobox and an install target that places the binary, man pages, completions and subcommand symlinks under PREFIX, which defaults to /usr/local.

### How do I use distrobox export?

distrobox-export is one of the commands that runs inside the container, and the usage documentation has a dedicated page for it. The useful tips page also has an export to the host section describing how an application or binary is made available on the host.

## Sources

- [Official documentation](https://distrobox.it/)
- [Official README](https://github.com/89luca89/distrobox#readme)
- [Project repository](https://github.com/89luca89/distrobox)
- [Release notes](https://github.com/89luca89/distrobox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/89luca89-distrobox