Gaming Linux® From Scratch (System V Edition) - Version #6336

Chapter 10. Graphics Drivers - NVIDIA

NVIDIA-590.48.01

Introduction to NVIDIA

The NVIDIA proprietary driver contains firmware, kernel drivers, userland drivers pertaining to OpenGL, Vulkan, and hardware acceleration, and provides useful utilities for Turing and later NVIDIA cards.

[Note]

Note

NVIDIA-Powerd is only supported on Systemd.

Additional Downloads

NVIDIA Dependencies

Required
GBM (libgbm-1.0.4 or Mesa-25.3.1), libglvnd-1.7.0, and Xorg Libraries

Recommended

Preparing for the NVIDIA Installation

First enable XFree86 DRI and Nouveau [4] support in the kernel and recompile if necessary. 

Device Drivers --->
  Graphics support --->
    <*/M> Direct Rendering Manager (XFree86 4.1.0 and higher DRI support) --->
                                                                      ...  [DRM]
    <M>   Nouveau (NVIDIA) cards                                   [DRM_NOUVEAU]
    Frame buffer Devices --->
      <M>   nVidia Framebuffer Support                               [FB_NVIDIA]
      < /M> Simple framebuffer support                               [FB_SIMPLE]
[Important]

Important

Build these drivers as kernel modules so that they can properly be blacklisted.

Extract the NVIDIA driver runfile and navigate to the extracted directory: 

sh NVIDIA-Linux-x86_64-590.48.01.run -x &&
cd NVIDIA-Linux-x86_64-590.48.01

Installation of the NVIDIA Kernel Modules

Change into the kernel-open directory: 

cd kernel-open
[Note]

Note

If the currently running kernel is a different version than you are targeting, likely as a result of being in a chroot or haven't rebooted after a kernel upgrade yet, building the kernel modules will cause a build failure or will install modules for a kernel that is not the target. The default variable that the kernel build system uses to check for the kernel version will use uname -r, in turn reporting the kernel version of the currently running host kernel and not the target. This can be worked around by specifying KERNEL_UNAME=<x.x.x> which will override the kernel version to build against and install to. The target kernel version must have already been built for this to work. If the kernel version doesn't have a third digit, like 6.16 instead of 6.16.1, append a .0 at the end, like 6.16.0. It should match the version found in /usr/lib/modules.

If the above case apply to you, whether you're in a chroot or haven't yet rebooted after a kernel upgrade, specify the kernel target by exporting the variable now ahead of time to prevent needing to specify it for every command: 

export KERNEL_UNAME=<x.x.x>

There will be 5 or 6 kernel modules that will be built. Depending on your use case, you can skip building a module or two. The UVM (Unified Virtual Memory) module is for use with CUDA. If you won't use it, nor wish to use its capabilities, you can skip building the UVM kernel module. There is also the PeerMem module which is for datacenters. For gaming, it can safely be disabled.

For UVM, the module is named nvidia-uvm. For PeerMem, it will be named nvidia-peermem. To skip these, add the module names to the NV_EXCLUDE_KERNEL_MODULES for the make command. The variable should be separated, as such: NV_EXCLUDE_KERNEL_MODULES="nvidia-uvm nvidia-peermem". The make command will have the variable set to nothing. Add to it as you see fit.

Now build the kernel modules by running the following command: 

make NV_EXCLUDE_KERNEL_MODULES=
[Note]

Note

The source code you built the kernel from must be in the same location you built the kernel. For example, if you built the kernel in /sources/linux-6.16.1, the source code should stay there and must not be deleted until the 3rd party modules have been built. Some Linux distributions get around this by installing development files in /usr/src, but that is out of the scope of this book.

[Note]

Note

You may encounter various build failures. This usually happens because the module code is incompatible with the current kernel version. If this happens, in most cases it can be fixed by downgrading the kernel. When a new driver release happens, the driver will then most likely support the kernel version at the time. At the top of this section, the recommended kernel series to use with this driver is mentioned to give an idea of what is the idea kernel version to build against.

[Important]

Important

When you rebuild/upgrade the kernel, you will also need to reinstall the NVIDIA kernel modules.

Kernel modules are installed in a versioned directory that, when they are built against a different kernel version, will no longer match the booted kernel version and cannot be used. Furthermore, there is glue built, so any changes to the kernel can break that glue. For kernel modules in the Linux source tree, known as first-party modules, they get updated and rebuilt alongside the kernel, so issues aren't ran into for first-party modules. Third-party modules aren't, however, and need to be updated/rebuilt.

When you rebuild/upgrade the kernel against the same NVIDIA driver version, you will only need to reinstall the kernel modules. You will have to reinstall the driver software as well if you are upgrading from a previous driver version.

Now as the root user: 

make modules_install &&
cd ..

If you set the KERNEL_UNAME variable, unset it now: 

unset KERNEL_UNAME

Install the firmware as the root user: 

rm -rvf /usr/lib/firmware/nvidia/[0-9]* &&
mkdir -pv /usr/lib/firmware/nvidia/590.48.01 &&
cp -v firmware/*.bin /usr/lib/firmware/nvidia/590.48.01

Installing the NVIDIA Driver Software

Install the install script and manifest file for the script as the root user: 

install -vdm755 /usr/share/nvidia &&
install -vDm755 ../install-NVIDIA-2 /usr/sbin/nvidia-install &&
install -vDm644 ../manifest-NVIDIA-2 /usr/share/nvidia/manifest

Now see what options there are and what you want to install by running /sbin/nvidia-install --help.

If you want to do the default installation, you can just run the following command as the root user: 

/sbin/nvidia-install
[Important]

Important

If you are booted into the system you are running the commands for, doing so for the above command in a graphical environment may crash that environment and drop you back to a TTY. Don't do that, just run it from a TTY or in a chroot where the display doesn't rely on the libraries provided from this driver. As for the TTY, it is actually driven by the kernel or its modules, not the libraries. That is why running the above command in a TTY is safe—it doesn't overwrite the kernel modules.

Configuring NVIDIA

Config Files

/usr/lib/modprobe.d/nouveau.conf

/usr/lib/modprobe.d/nvidia_drm.conf

List of Packages With Issues

Using this driver can come with compromises. So far, these issues seem to be limited to Wayland and window managers. The list below documents the known packages that have issues with this driver.

  • Mutter: Compile this package with -D wayland_eglstream=true and -D egl_device=true to enable launching with Wayland. Ensure the NVIDIA EGL Libraries are installed.

  • Xorg-Server-21.1.20: While this package works just fine, the TearFree patch and configuration file will be useless as the Xorg driver (nvidia_drv) will be used instead of the modesetting driver. The TearFree patch and configuration file is modesetting-specific. Thus, you must find another way to get rid of screen tearing if that is your wish. Such fixes may bog down performance drastically such that 144 FPS may drop to 60 FPS.

Configuration Information

In order for the drivers to work properly, device nodes must be created beforehand. Under certain conditions or configurations, these aren't created automatically when starting a display server. As the root user, create a udev rule to always create these nodes at boot time: 

mkdir -pv /usr/lib/udev/rules.d &&
cat > /usr/lib/udev/rules.d/60-nvidia.rules << "EOF"
# Always create NVIDIA device nodes at boot time.
ACTION=="add|bind",                \
  ATTR{vendor}=="0x10de",          \
  ATTR{class}=="0x03[0-9]*",       \
  DRIVER=="nvidia",                \
  TEST!="/dev/nvidiactl",          \
  RUN+="/usr/bin/nvidia-modprobe", \
  RUN+="/usr/bin/nvidia-modprobe -c0 -u"
EOF

Nouveau and NVIDIAFB support was compiled into the kernel to make the NVIDIA kernel modules build successfully. However, Nouveau and NVIDIAFB conflict with the NVIDIA kernel modules, so they should be blacklisted. Furthermore, other modules may have been built that can conflict, and should likewise be disabled. As the root user, create the file /usr/lib/modprobe.d/nouveau.conf to blacklist Nouveau and NVIDIAFB, as well as other conflicting modules: 

mkdir -pv /usr/lib/modprobe.d &&
cat > /usr/lib/modprobe.d/nouveau.conf << "EOF"
# Begin /usr/lib/modprobe.d/nouveau.conf

blacklist nouveau
blacklist nvidiafb
blacklist nova_core
blacklist nova_drm

# End /usr/lib/modprobe.d/nouveau.conf
EOF

The DRM kernel module does not use modesetting by default which is needed by Wayland compositors. Make it use modesetting as the root user: 

cat > /usr/lib/modprobe.d/nvidia_drm.conf << "EOF"
# Begin /usr/lib/modprobe.d/nvidia_drm.conf

options nvidia_drm modeset=1

# End /usr/lib/modprobe.d/nvidia_drm.conf
EOF

This driver does not install DRI [5] drivers or driver stubs. Likewise, it does not install a pkgconf file saying where to find the associated files. The files aren't needed with this driver. However, some applications expect the pkg-config file to exist, namely Xorg-Server-21.1.20. Create one now as the root user: 

cat > /usr/lib/pkgconfig/dri.pc << "EOF"
prefix=/usr
includedir=${prefix}/include

dridriverdir=/usr/lib/dri

Name: dri
Description: Direct Rendering Infrastructure
Version: 590.48.01
Requires.private: libdrm >=  2.4.109
Cflags: -I${includedir}
EOF

Applications that do require this file typically will not link against any library in /usr/lib/dri. If you are worried that an application will try to link against non-existent libraries, you can compile Mesa-25.3.1 to get these libraries and a real pkg-config file. Note that those libraries will not be used when this driver is in use.

Like with the situation regarding DRI, there are a few header files only installed by Mesa-25.3.1 but can be dropped in without an issue. One is for declaring the DRI interface, one for declaring Mesa's EGL EXT system that is used by some software like GNOME's mutter, and another for declaring the EGL EXT system for ANGLE, with modifications geared for it. Using Wget-1.25.0, download and install them as the root user: 

install -vdm755 /usr/include/GL/internal /usr/include/EGL &&
wget https://gitlab.freedesktop.org/mesa/mesa/-/raw/25.3/include/GL/internal/dri_interface.h \
  -O /usr/include/GL/internal/dri_interface.h &&
wget https://gitlab.freedesktop.org/mesa/mesa/-/raw/25.3/include/EGL/eglmesaext.h \
  -O /usr/include/EGL/eglmesaext.h &&
wget https://gitlab.freedesktop.org/mesa/mesa/-/raw/25.3/include/EGL/eglext_angle.h \
  -O /usr/include/EGL/eglext_angle.h

Proceeding

If you put all the files in place in the configuration section, you should not need Mesa for any packages in the book or in BLFS. The OpenGL, DRI, and EGL files provided here should be suitable enough. GNOME and KDE are known to work with this configuration.

With this pure NVIDIA-only setup, you can skip to Chapter 12, X11 and expect smooth sailing. If you want to however, you can also install CUDA in this subsection, which up to you.

Contents

Installed Programs: nvidia-install, nvidia-modprobe, nvidia-settings, nvidia-smi, and nvidia-xconfig
Installed Firmware: gsp_ga10x.bin and gsp_tu10x.bin
Installed Libraries: libcudadebugger, libcuda, libEGL_nvidia, libGLESv1_CM_nvidia, libGLESv2_nvidia, libGLX_nvidia, libglxserver_nvidia, libnvcuvid, libnvoptix, libnvidia-allocator, libnvidia-api, libnvidia-cfg, libnvidia-eglcore, libnvidia-encode, libnvidia-fbc, libnvidia-glcore, libnvidia-glsi, libnvidia-glvkspirv, libnvidia-gpucomp, libnvidia-gtk3, libnvidia-ml, libnvidia-ngx, libnvidia-nvvm{70,}, libnvidia-opencl, libnvidia-opticalflow, libnvidia-pkcs11-openssl3, libnvidia-pkcs11, libnvidia-ptxjitcompiler, libnvidia-rtcore, libnvidia-tileiras, libnvidia-tls, libnvidia-wayland-client, libOpenCL, nvidia-drm_gbm, nvidia_drv, and for Wine-10.20 (_nvngx, nvngx, and nvngx_dlssg; all three are DLLs)
Installed Directories: /usr/lib/firmware/nvidia/590.48.01, /usr/lib/nvidia/wine, /usr/share/glvnd/egl_vendor.d, and /usr/share/nvidia

Short Descriptions

nvidia-install

is an install script that installs all the software from this driver that you need

nvidia-modprobe

is a suid program which populates /dev with directories and files for this driver and is loaded when starting a display server

nvidia-settings

a GUI application relying on GTK-3 that allows tweaking settings like resolution and refresh rate

nvidia-smi

provides NVIDIA GPU monitoring information

nvidia-xconfig

manipulates X11 configuration files to allow the NVIDIA driver to be used when starting X11

libcudadebugger

allows debugging CUDA applications

libcuda

provides support for applications that use CUDA

libEGL_nvidia

provides the NVIDIA implementation of EGL

libGLESv1_CM_nvidia

provides the NVIDIA implementation of the OpenGL ES v1 common profile

libGLESv2_nvidia

provides the NVIDIA implementation of OpenGL ES v2 and v3

libGLX_nvidia

provides the NVIDIA implementation of GLX

libglxserver_nvidia

is the NVIDIA X11 GLX extension module

libnvcuvid

provides an interface to hardware accelerated decoding

libnvoptix

provides the OptiX Ray Tracing API

libnvidia-allocator

handles NVIDIA GPU memory management

libnvidia-api

provides the NVAPI interface

libnvidia-cfg

queries a NVIDIA GPU's configuration settings

libnvidia-eglcore

provides primary EGL functionality to other components of the driver

libnvidia-encode

provides an interface to video encoder hardware

libnvidia-fbc

provides an interface to capture and optionally encode the framebuffer of an X11 server screen

libnvidia-glcore

provides the primary OpenGL functionality for other components of this driver

libnvidia-glsi

provides the OpenGL Shader Interface for other components of this driver

libnvidia-glvkspirv

allows using SPIR-V shaders in OpenGL

libnvidia-gpucomp

provides primary functionality for allowing computations being done on the GPU for use with other components in this driver

libnvidia-gtk3

for nvidia-settings; utilizes GTK-3

libnvidia-ml

provides a monitoring and management API

libnvidia-ngx

provides functions for DLSS support

libnvidia-nvvm

provides JIT LTO for CUDA

libnvidia-opencl

provides NVIDIA's implementation of the OpenCL API standard

libnvidia-opticalflow

provides Optical Flow support which improves frames, similar to DLSS, with the help of CUDA

libnvidia-pkcs11

provides cryptography functions when the driver is operating in Confidential Compute mode

libnvidia-ptxjitcompiler

is a JIT compiler which compiles PTX into GPU machine code; used by CUDA

libnvidia-rtcore

implements the RT (Ray Tracing) core functionality and is used by other components in this driver

libnvidia-tileiras

provides the TileIR interface, representing CUDA kernels to various programming languages

libnvidia-tls

provides TLS support for the NVIDIA OpenGL implementations

libnvidia-wayland-client

is required for nvidia-settings on Wayland

libOpenCL

is the OpenCL loader that opens a given OpenCL driver

_nvngx

provides DLSS support for use with Proton

nvngx

provides DLSS support for use with Wine

nvngx_dlssg

is the DLSS 3 Frame Generation library

nvidia-drm_gbm

is the GBM backend for NVIDIA drivers

nvidia_drv

is the NVIDIA X11 driver


[4] NVIDIA's kernel modules will fail to compile with TTY support unless a graphics driver is included in the kernel. Nouveau is used here, though alternate graphics drivers may also work.

[5] Direct Rendering Infrastructure.