nix-community/home-manager
1
0
Fork 0
mirror of https://github.com/nix-community/home-manager.git synced 2025-12-02 23:21:02 +01:00
Code Activity

docs/generic-linux-gpu: add instructions to manual

Browse source
This commit is contained in:
Jure Varlec 2025-10-22 20:53:43 +02:00 • committed by Austin Horstman
parent 77b51dbb9f
commit d8efc4bfa7
1 changed files with 120 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

123
docs/manual/usage/gpu-non-nixos.md
View file

@ -1,9 +1,126 @@
# GPU on non-NixOS systems {#sec-usage-gpu-non-nixos}
To access the GPU, programs need access to OpenGL and Vulkan libraries. While
this works transparently on NixOS, it does not on other Linux systems. A
solution is provided by [NixGL](https://github.com/nix-community/nixGL), which
can be integrated into Home Manager.
this works transparently on NixOS, it does not on other Linux systems. There are
two options:
1. Recommended: modify the host system slightly so that the graphics libraries
can be found where programs from Nixpkgs can find them.
2. Wrap programs from Nixpkgs in an environment which tells them where to find
graphics libraries.
The first option is very clean because the needed modifications to the host OS
are small. However, it does require root/sudo access to the system, which may
not be available. The second approach avoids that. However, it injects libraries
from Nixpkgs into the environment of wrapped programs, which can make it
impossible to launch programs of the host OS from wrapped programs.
## When sudo is available: fixing the host OS {#sec-usage-gpu-sudo}
The {option}`targets.genericLinux.gpu` module is automatically enabled whenever
the option {option}`targets.genericLinux.enable` is set (unless
[NixGL](#sec-usage-gpu-nosudo) is used instead), which is recommended for
non-NixOS Linux distributions in any case. The module can also be explicitly
enabled by setting {option}`targets.genericLinux.gpu.enable`.
This module builds a directory containing GPU libraries. When activating the
home configuration by `home-manager switch`, the host system is examined: for
compatibility with NixOS, these libraries need to be placed in
`/run/opengl-driver`. If this directory does not exist, or contains a different
set of libraries, the activation script will print a warning such as
```text
Activating checkExistingGpuDrivers
GPU drivers require an update, run
sudo /nix/store/HASH-non-nixos-gpu/bin/non-nixos-gpu-setup
```
Because the `/run` directory is volatile and disappears on reboot, libraries
cannot be simply copied or linked there. The `non-nixos-gpu-setup` script
installs a Systemd service which ensures that the drivers are linked to
`/run/opengl-driver` on boot. Home Manager will always check and warn you when
this setup needs to be refreshed.
If you ever wish to uninstall these drivers, all you need to do is
```sh
sudo rm /run/opengl-driver
sudo systemctl disable --now non-nixos-gpu.service
sudo rm /etc/systemd/system/non-nixos-gpu.service
```
### GPU offloading {#sec-usage-gpu-offloading}
You can use the {option}`targets.genericLinux.nixGL.prime.installScript` option.
It installs the `prime-offload` script which is configured through options under
{option}`targets.genericLinux.nixGL.prime`. This functionality is independent
from the rest of NixGL and can be used when
{option}`targets.genericLinux.nixGL.packages` is left `null`, which it should be
when using drivers from `/run/opengl-driver`.
### Nvidia drivers {#sec-usage-gpu-nvidia}
If you need to include the proprietary Nvidia drivers, the process is a bit more
involved. You need to:
1. Determine the exact version used by the host system. Example: `550.163.01`
1. Fetch that version of the drivers from Nvidia and calculate their hash.
Example:
```sh
nix store prefetch-file \
https://download.nvidia.com/XFree86/Linux-x86_64/550.163.01/NVIDIA-Linux-x86_64-550.163.01.run
```
Attention: the version and architecture are present twice. If you are on an
ARM system, replace `x86_64` with `aarch64`.
1. Put this information into your home configuration. Example:
```nix
targets.genericLinux.gpu.nvidia = {
enable = true;
version = "550.163.01";
sha256 = "sha256-74FJ9bNFlUYBRen7+C08ku5Gc1uFYGeqlIh7l1yrmi4=";
};
```
::: {.warning}
The Nvidia driver version **must** match the host system. This means that you
must pay attention when upgrading the system and update the home configuration
as well.
:::
## No root access: wrapping programs {#sec-usage-gpu-nosudo}
The wrapping approach is facilitated by
[NixGL](https://github.com/nix-community/nixGL), which can be integrated into
Home Manager.
::: {.warning}
This approach can cause issues when a wrapped program from Nixpkgs executes a
program from the host. For example, Firefox from Nixpkgs must be wrapped by
NixGL in order for graphical acceleration to work. If you then download a PDF
file and open it in a PDF viewer that is not installed from Nixpkgs but is
provided by the host distribution, there may be issues. Because Firefox's
environment injects libraries from NixGL, they are inherited by the PDF viewer,
and unless they are the same or compatible version as the libraries on the host,
the viewer will not work. This problem manifests more often with Vulkan because
it needs a larger set of injected libraries than OpenGL.
The problem typically manifests with errors similar to
```text
/nix/store/HASH-gcc-12.3.0-lib/lib/libstdc++.so.6: version `GLIBCXX_3.4.31' not found
```
:::
To enable the integration, import NixGL into your home configuration, either as
a channel, or as a flake input passed via `extraSpecialArgs`. Then, set the