View source for Distrobox

[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 Arch Linux] image

<syntaxhighlight lang="console">
distrobox create --root --name archlinux --init --image archlinux:latest
</syntaxhighlight>

Enter Arch Linux container

<syntaxhighlight lang="console">
distrobox enter --root archlinux
</syntaxhighlight>

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 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]]