Distrobox: Difference between revisions

(18 intermediate revisions by 7 users not shown)

Line 1:

[https://distrobox.it Distrobox] offers you to use any linux distribution inside your terminal as a simple wrapper for Docker.

[https://distrobox.it Distrobox] offers you to use any linux distribution inside your terminal as a simple wrapper for [[Podman]], [[Docker]] or Lilipod.

== Setup ==

Distrobox uses Docker internally to fetch and run system images. Easily get started by enabling Podman with Docker-compatibility mode.<syntaxhighlight lang="nix">

virtualisation.podman = {

enable = true;

dockerCompat = true;

};

environment.systemPackages = [ pkgs.distrobox ];

</syntaxhighlight>

== Usage ==

Setup container with latest [https://archlinux.org ~~Archlinux~~] image

Setup container with latest [https://archlinux.org Arch Linux] image

distrobox create --root --name archlinux --init --image archlinux:latest

</syntaxhighlight>

Enter Arch Linux container

# distrobox ~~create~~ --~~name~~ archlinux ~~--init --image archlinux:latest~~

distrobox enter --root archlinux

</syntaxhighlight>

~~Enter Archlinux~~ container

For further usage, please refer to the [https://distrobox.it/#distrobox Distrobox] documentation.

== Tips and tricks ==

=== Using different architecture ===

The following example will run an Ubuntu container with a different architecture than the host, in this case arm64.

Add following line to your system configuration, apply it and then reboot the system.<syntaxhighlight lang="nix">

boot.binfmt.emulatedSystems = [ "aarch64-linux" ];

</syntaxhighlight>Run a Debian container with arm64 architecture<syntaxhighlight lang="nix">

sudo podman run --rm --privileged multiarch/qemu-user-static --reset -p yes

distrobox create -n debian --image arm64v8/debian

distrobox enter debian

</syntaxhighlight>

=== "potentially insufficient UIDs and GUIDs" error ===

When setting up containers that do not run as root, as <code>podman</code> does by default, you may see an error along the following lines: (this example uses podman, lilipod has a different error)

# distrobox ~~enter archlinux~~

# distrobox create container

...

Error: copying system image from manifest list: writing blob: adding layer with blob ...:

unpacking failed (error: exit status 1;

output: potentially insufficient UIDs or GIDs available in user namespace (requested 1000:1000 for /home/container): Check /etc/subuid and /etc/subgid if configured locally and run "podman system migrate": lchown /home/container: invalid argument)

</syntaxhighlight>

To fix it, adding the following to your config might help:

users.users.YOURUSERNAME = {

extraGroups = [ "podman" ];

subGidRanges = [

{

count = 65536;

startGid = 1000;

}

];

subUidRanges = [

{

count = 65536;

startUid = 1000;

}

];

};

</syntaxhighlight>

Rebuild your system, run <code>podman system migrate</code>, and try creating the distrobox container again.

=== Exposing your profile ===

If you get errors like <code>/home/user/.zshenv:.:2: no such file or directory: /etc/profiles/per-user/user/etc/profile.d/hm-session-vars.sh</code> or <code>_atuin_preexec: command not found: atuin</code> that is because your shell init is referencing paths that are not accessible to Distrobox. By default, Distrobox only gets access to your home directory. You can mount additional volumes with <code>distrobox create --volume /your/custom/volume/path</code>, but it is more convenient to define defaults in <code>distrobox.conf</code>: <syntaxhighlight lang="nix">environment.etc."distrobox/distrobox.conf".text = ''

container_additional_volumes="/nix/store:/nix/store:ro /etc/profiles/per-user:/etc/profiles/per-user:ro /etc/static/profiles/per-user:/etc/static/profiles/per-user:ro"

''; </syntaxhighlight>

[[Category:Applications]]

[[Category:Container]]

== Known Issues ==

=== Distrobox Fails With Arch Linux and init ===

This is a cross-distro (not NixOS-specific) issue resulting from a [https://github.com/util-linux/util-linux/ util-linux] runuser regression.<ref name="debian-report">https://github.com/89luca89/distrobox/issues/2069</ref><ref name="nixos-report">https://github.com/89luca89/distrobox/issues/2065</ref> A fix has recently been merged, and the issue should be resolved in the next release (v2.43).<ref name="util-linux-pull">https://github.com/util-linux/util-linux/pull/4185</ref>.

=== Distrobox is not location independent ===

The symptom is that a distrobox container created in the past can not run, because it references a non-existing "distrobox-init" script as a necessary bind mount.

Historically, this was a known issue<ref>https://github.com/89luca89/distrobox/issues/315</ref> affecting users who have created a container with a different version of distrobox than the one that is currently running. It can surface after running GC. The root cause is that the container is created with bind mounts for essential scripts, one of which is the entrypoint itself, the source of which is often an absolute path, such as: <code>/nix/store/XXXXX-distrobox/bin/distrobox-init</code>. The problem is that once a container was created with a bind mount, its source has to be available every time the container is re-executed.

This issue was solved 2 times upstream, both in 2022:

The first solution<ref>https://github.com/89luca89/distrobox/commit/52a34fbd52e1f0f035657b167ebe997d41db0993</ref> replaces the bind-mount with copying the scripts into the container during distrobox-enter.

The second solution<ref>https://github.com/89luca89/distrobox/commit/1ad3204ee78dfb8ee772cdd81788f3cbb3f4bd1b</ref> reverts the first solution, due to problems the former had introduced with btrfs. In order to avoid regressions for Nix users, it introduces a weaker solution for mounting the scripts: instead of <code>realpath</code>, it makes use of: <code>cd "$(dirname "${0}")" && pwd</code>. That works, but only as long as:

# The "$0" argument is preserved. There was an [https://github.com/NixOS/nixpkgs/issues/478154 issue in nixpkgs], fixed in 2026<ref>https://github.com/NixOS/nixpkgs/commit/2f87ef8fdbabc6df0fbaf59ad14598864711ed4c</ref>, with non-preservation of "$0" in the "distrobox" command wrapper. Direct calls to <code>distrobox-create</code> were unaffected.

# In every future execution of the container, the distrobox utilities will remain in the same path. This is workable when the installation is fixed on a path like <code>/run/current-system/sw/bin/distrobox-init</code>.

Notably, if you were affected by the first issue, then your container will not work even after the fixes that have since come out. The second issue is not resolved due to decisions upstream.

== References ==

@@ Line 1: / Line 1: @@
-[https://distrobox.it Distrobox] offers you to use any linux distribution inside your terminal as a simple wrapper for Docker.
+[https://distrobox.it Distrobox] offers you to use any linux distribution inside your terminal as a simple wrapper for [[Podman]], [[Docker]] or Lilipod.
+== Setup ==
+Distrobox uses Docker internally to fetch and run system images. Easily get started by enabling Podman with Docker-compatibility mode.<syntaxhighlight lang="nix">
+virtualisation.podman = {
+  enable = true;
+  dockerCompat = true;
+};
+environment.systemPackages = [ pkgs.distrobox ];
+</syntaxhighlight>
 == Usage ==
-Setup container with latest [https://archlinux.org Archlinux] image
+Setup container with latest [https://archlinux.org Arch Linux] image
+<syntaxhighlight lang="console">
+distrobox create --root --name archlinux --init --image archlinux:latest
+</syntaxhighlight>
+Enter Arch Linux container
 <syntaxhighlight lang="console">
-# distrobox create --name archlinux --init --image archlinux:latest
+distrobox enter --root archlinux
 </syntaxhighlight>
-Enter Archlinux container
+For further usage, please refer to the [https://distrobox.it/#distrobox Distrobox] documentation.
+== Tips and tricks ==
+=== Using different architecture ===
+The following example will run an Ubuntu container with a different architecture than the host, in this case arm64.
+Add following line to your system configuration, apply it and then reboot the system.<syntaxhighlight lang="nix">
+boot.binfmt.emulatedSystems = [ "aarch64-linux" ];
+</syntaxhighlight>Run a Debian container with arm64 architecture<syntaxhighlight lang="nix">
+sudo podman run --rm --privileged multiarch/qemu-user-static --reset -p yes
+distrobox create -n debian --image arm64v8/debian
+distrobox enter debian
+</syntaxhighlight>
+=== "potentially insufficient UIDs and GUIDs" error ===
+When setting up containers that do not run as root, as <code>podman</code> does by default, you may see an error along the following lines: (this example uses podman, lilipod has a different error)
 <syntaxhighlight lang="console">
-# distrobox enter archlinux
+# distrobox create container
+...
+Error: copying system image from manifest list: writing blob: adding layer with blob ...:
+unpacking failed (error: exit status 1;
+output: potentially insufficient UIDs or GIDs available in user namespace (requested 1000:1000 for /home/container): Check /etc/subuid and /etc/subgid if configured locally and run "podman system migrate": lchown /home/container: invalid argument)
+</syntaxhighlight>
+To fix it, adding the following to your config might help:
+<syntaxhighlight lang="nix">
+  users.users.YOURUSERNAME = {
+      extraGroups = [ "podman" ];
+      subGidRanges = [
+          {
+              count = 65536;
+              startGid = 1000;
+          }
+      ];
+      subUidRanges = [
+          {
+              count = 65536;
+              startUid = 1000;
+          }
+      ];
+  };
 </syntaxhighlight>
+Rebuild your system, run <code>podman system migrate</code>, and try creating the distrobox container again.
+=== Exposing your profile ===
+If you get errors like <code>/home/user/.zshenv:.:2: no such file or directory: /etc/profiles/per-user/user/etc/profile.d/hm-session-vars.sh</code> or <code>_atuin_preexec: command not found: atuin</code> that is because your shell init is referencing paths that are not accessible to Distrobox. By default, Distrobox only gets access to your home directory. You can mount additional volumes with <code>distrobox create --volume /your/custom/volume/path</code>, but it is more convenient to define defaults in <code>distrobox.conf</code>: <syntaxhighlight lang="nix">environment.etc."distrobox/distrobox.conf".text = ''
+  container_additional_volumes="/nix/store:/nix/store:ro /etc/profiles/per-user:/etc/profiles/per-user:ro /etc/static/profiles/per-user:/etc/static/profiles/per-user:ro"
+''; </syntaxhighlight>
 [[Category:Applications]]
 [[Category:Container]]
+== Known Issues ==
+=== Distrobox Fails With Arch Linux and init ===
+This is a cross-distro (not NixOS-specific) issue resulting from a [https://github.com/util-linux/util-linux/ util-linux] runuser regression.<ref name="debian-report">https://github.com/89luca89/distrobox/issues/2069</ref><ref name="nixos-report">https://github.com/89luca89/distrobox/issues/2065</ref> A fix has recently been merged, and the issue should be resolved in the next release (v2.43).<ref name="util-linux-pull">https://github.com/util-linux/util-linux/pull/4185</ref>.
+=== Distrobox is not location independent ===
+The symptom is that a distrobox container created in the past can not run, because it references a non-existing "distrobox-init" script as a necessary bind mount.
+Historically, this was a known issue<ref>https://github.com/89luca89/distrobox/issues/315</ref> affecting users who have created a container with a different version of distrobox than the one that is currently running. It can surface after running GC. The root cause is that the container is created with bind mounts for essential scripts, one of which is the entrypoint itself, the source of which is often an absolute path, such as: <code>/nix/store/XXXXX-distrobox/bin/distrobox-init</code>. The problem is that once a container was created with a bind mount, its source has to be available every time the container is re-executed.
+This issue was solved 2 times upstream, both in 2022:
+The first solution<ref>https://github.com/89luca89/distrobox/commit/52a34fbd52e1f0f035657b167ebe997d41db0993</ref> replaces the bind-mount with copying the scripts into the container during distrobox-enter.
+The second solution<ref>https://github.com/89luca89/distrobox/commit/1ad3204ee78dfb8ee772cdd81788f3cbb3f4bd1b</ref> reverts the first solution, due to problems the former had introduced with btrfs. In order to avoid regressions for Nix users, it introduces a weaker solution for mounting the scripts: instead of <code>realpath</code>, it makes use of: <code>cd "$(dirname "${0}")" && pwd</code>. That works, but only as long as:
+# The "$0" argument is preserved. There was an [https://github.com/NixOS/nixpkgs/issues/478154 issue in nixpkgs], fixed in 2026<ref>https://github.com/NixOS/nixpkgs/commit/2f87ef8fdbabc6df0fbaf59ad14598864711ed4c</ref>, with non-preservation of "$0" in the "distrobox" command wrapper. Direct calls to <code>distrobox-create</code> were unaffected.
+# In every future execution of the container, the distrobox utilities will remain in the same path. This is workable when the installation is fixed on a path like <code>/run/current-system/sw/bin/distrobox-init</code>.
+Notably, if you were affected by the first issue, then your container will not work even after the fixes that have since come out. The second issue is not resolved due to decisions upstream.
+== References ==
+<references/>