---
obj: application
website: https://distrobox.it
arch-wiki: https://wiki.archlinux.org/title/Distrobox
repo: https://github.com/89luca89/distrobox
---

# 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, 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.

## Usage
To create a new container run the following:
```
$ distrobox create -n name
```

To list installed containers run the following:
```
$ distrobox list
```

To interact with an installed container run the following:
```
$ distrobox enter name
```

or you can send a command directly to a container with:
```
$ distrobox enter name -- command-to-execute
```

To stop a running container run the following:
```
$ distrobox stop name
```

To delete a container run the following:
```
$ distrobox rm name
```

To install a specific distro into a container run the following (in this example it is Ubuntu):
```
$ distrobox create --image ubuntu:22.04
```

Installations can be fully customised as follows (in this example it is a container called test running Gentoo with root access):
```
$ distrobox create -i docker.io/gentoo/stage3:latest -n test --root
```

If you need your container to have root access to the host then it is recommended that you use the `--root` flag over `sudo distrobox`.

### Unsharing mode
Distrobox allows users to partially isolate certain system aspects through its unshare feature. By default, the following components are shared between host and container:

`devsysfs`, `ipc`, `netns`, `process`, `$HOME` and Application access.

You can choose to unshare some of these components by using the commands listed below when creating a new container:

#### Shares

| Share      | Command              | Usage                                               |
| ---------- | -------------------- | --------------------------------------------------- |
| `devsysfs` | `--unshare-devsysfs` | Do not share host devices and sysfs dirs from host. |
| `ipc`      | `--unshare-ipc`      | Do not share the ipc namespace with host.           |
| `netns`    | `--unshare-netns`    | Do not share the network namespace with host.       |
| `process`  | `--unshare-process`  | Do not share the process namespace with host.       |
| All        | `--unshare-all`      | Activate all unshare flags.                         |

Note that unsharing `$HOME` and Application access is not possible, as these are mandatory for Distrobox's core functionality.

> Warning: While the unsharing feature provides some isolation between container and host, it does not constitute a full security sandbox. You should not rely on it for complete security isolation.

## Configuration
It is possible to configure Distrobox in two ways, either with a configuration file or by using environment variables.

### Configuration file
Distrobox checks the following locations for config files, from least important to most important:

- `/usr/share/distrobox/distrobox.conf`
- `/usr/etc/distrobox/distrobox.conf`
- `/etc/distrobox/distrobox.conf`
- `~/.config/distrobox/distrobox.conf`
- `~/.distroboxrc`

An example config file is as follows:
```
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"
```

### Environment variables
The following variables are available and should be set using per user 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
```
