Distrobox: Difference between revisions

Latest revision as of 14:03, 28 October 2025

Distrobox is a container wrapping layer that uses a container such as Podman, Docker, etc., to run your choice of Linux distribution or GUI apps (both Wayland and X11) from a terminal while enabling the use of the user's $HOME directory and external USB devices and storage. It runs on the Linux kernel natively. As a launcher of containers, it is distinct from WebAssembly (Wasm).

Installation

Installing the distrobox package automatically installs Podman as a dependency upon 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 environments like Sway run without xwayland on the Alpine Linux host, electron apps such as code-oss, vscodium, or chromium, etc., need to be started as follows:

$ distrobox enter my-debian -- code --enable-features=UseOzonePlatform,WaylandWindowDecorations --ozone-platform=wayland

If you are running an X11 desktop, it may also be necessary to allow X authorization in order for GUI programs to work:

$ xhost +si:localuser:$USER

@@ Line 1: / Line 1: @@
-[https://distrobox.it/ 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.
+[https://distrobox.it/ Distrobox] is a container wrapping layer that uses a container such as [[Podman]], [[Docker]], etc., to run your choice of Linux distribution or GUI apps (both '''Wayland''' and '''X11''') from a terminal while enabling the use of the user's {{Path|$HOME}} directory and external USB devices and storage. It runs on the Linux kernel natively.  As a launcher of containers, it is distinct from [https://webassembly.org/ WebAssembly (Wasm)].
 == Installation ==
-Installing {{pkg|distrobox}} package automatically installs [[Podman]] as a dependency, on issuing the command:{{cmd|# apk add {{pkg|distrobox}}}}
+Installing the {{pkg|distrobox}} package automatically installs [[Podman]] as a dependency upon issuing the command:
+{{cmd|# apk add {{pkg|distrobox}}}}
 == Running graphical programs ==
@@ Line 9: / Line 10: @@
 Configure Podman to run in [[Podman#Running in rootless mode|rootless mode]].
-Create a container using an image of your choice. Here Debian is installed using the command:{{cmd|$ distrobox create --name my-debian --image debian
+Create a container using an image of your choice. Here, Debian is installed using the command:
+{{cmd|$ distrobox create --name my-debian --image debian
 $ distrobox enter my-debian}}
-When [[Wayland]] desktop like [[Sway]] runs without {{pkg|xwayland}} on the Alpine Linux host, electron apps like {{ic|vscode}}, {{ic|google-chrome}} etc needs to be started as follows:{{ic|<nowiki>$ distrobox enter my-debian -- code --ozone-platform=wayland</nowiki>}}.
+When [[Wayland]] desktop environments like [[Sway]] run without {{pkg|xwayland}} on the Alpine Linux host, electron apps such as {{pkg|code-oss}}, {{pkg|vscodium}}, or {{pkg|chromium}}, etc., need to be started as follows:
+{{cmd|<nowiki>$ distrobox enter my-debian -- code --enable-features=UseOzonePlatform,WaylandWindowDecorations --ozone-platform=wayland</nowiki>}}
-If you are running X11 desktop, it may also be necessary to allow X authorization for GUI programs to work: {{ic|$ xhost +si:localuser:$USER}}
+If you are running an '''X11''' desktop, it may also be necessary to allow '''X''' authorization in order for GUI programs to work:
+{{cmd|$ xhost +si:localuser:$USER}}
 == Troubleshooting ==
-=== Permission problems with rootless Podman ===
-You may encounter an error when entering your rootless container:
-<code>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</code>
-This problem may be solved by installing {{Pkg|crun}}: {{Cmd|# apk add crun}}
-and recreating your container. Keep in mind that {{Pkg|crun}} replaces {{Pkg|runc}}, which will render containers made with the latter unusable until recreated.
 == See also ==