Distrobox

From Alpine Linux
Revision as of 20:19, 22 September 2025 by Lilith (talk | contribs) (add important remark to my earlier troubleshooting contribution)

Distrobox allows running any Linux distribution inside your terminal. Distrobox uses Podman, Docker etc.. to create containers using the Linux distribution of your choice. This enables both backward and forward compatibility with software and freedom to use whatever distribution you’re more comfortable with.

Installation

Installing distrobox package automatically installs Podman as a dependency, on issuing the command:

# apk add distrobox

Running graphical programs

Configure Podman to run in rootless mode.

Create a container using an image of your choice. Here Debian is installed using the command:

$ distrobox create --name my-debian --image debian $ distrobox enter my-debian

When Wayland desktop like Sway runs without xwayland on the Alpine Linux host, electron apps like vscode, google-chrome etc needs to be started as follows:$ distrobox enter my-debian -- code --ozone-platform=wayland.

If you are running X11 desktop, it may also be necessary to allow X authorization for GUI programs to work: $ xhost +si:localuser:$USER

Troubleshooting

Permission problems with rootless Podman

You may encounter an error when entering your rootless container:

Error: unable to start container "XYZ": runc: runc create failed: unable to start container process: unable to apply cgroup configuration: rootless needs no limits + no cgrouppath when no permission is granted for cgroups: mkdir /sys/fs/cgroup/XYZ: permission denied: OCI permission denied

This problem may be solved by installing crun:

# apk add crun

and recreating your container. Keep in mind that crun replaces runc, which will render containers made with the latter unusable until recreated.

See also