NVIDIA* Drivers

NVIDIA manufactures graphics processing units (GPU), also known as graphics cards.

NVIDIA devices on Linux* have two popular device driver options: the opensource drivers from the nouveau project or the proprietary drivers published by NVIDIA. The nouveau drivers are built into the Clear Linux* OS kernel and are loaded automatically at system boot if a compatible card is detected.

These instructions show how to use the proprietary NVIDIA drivers, which require a manual installation.

Warning

Software installed outside of swupd is not updated with Clear Linux OS updates and must be updated and maintained manually.

For example, the file /usr/lib/libGL.so conflicts with the file provided by the mesa package in Clear Linux OS and the file NVIDIA provides. If a Clear Linux OS update overwrites these files, a reinstallation of the NVIDIA driver might be required.

Prerequisites

  • A Clear Linux OS system with a desktop installed
  • An NVIDIA device installed

Note

NVIDIA Optimus

Some systems come with a hybrid graphics configuration for a balanced power and performance profile. This configuration is commonly found on laptops. NVIDIA Optimus* technology, is designed to allow switching seamlessly between a NVIDIA device and another graphics devices sharing the same display.

Getting NVIDIA Optimus* on Linux working well with both graphics devices adds an additional level of complexity with platform specific steps and may require additional software. Installation for systems with NVIDIA Optimus* with both graphics devices operating is not covered by the scope of this documentation. As a simple workaround, some systems can disable one of the graphics devices or NVIDIA Optimus* in the system firmware.

Installation

Install DKMS

The Dynamic Kernel Module System (DKMS) allows the NVIDIA kernel modules to be automatically integrated when kernel updates occur in Clear Linux OS.

Install the appropriate DKMS bundle using the instructions below:

Note

The Long Term Support (LTS) kernel variant is more likely to remain compatible between updates with NVIDIA drivers.

The kernel-native-dkms bundle provides the dkms program and Linux kernel headers, which are required for compiling kernel modules.

The kernel-native-dkms bundle also:

  • Adds a systemd update trigger (/usr/lib/systemd/system/dkms-new-kernel.service) to automatically run DKMS to rebuild modules after a kernel upgrade occurs with swupd update.
  • Disables kernel module signature verification by appending a kernel command-line parameter (module.sig_unenforce) from the /usr/share/kernel/cmdline.d/clr-ignore-mod-sig.conf file.
  • Adds a notification to the Message of the Day (MOTD) indicating kernel module signature verification is disabled.

Warning

We recommend that you always review the swupd update output to make sure kernel modules were successfully rebuilt against the new kernel. This is especially important for systems where a successful boot relies on a kernel module.

Install the kernel-native-dkms or kernel-lts-dkms bundle:

  1. Determine which kernel variant is running on Clear Linux OS. Only the native and lts kernels are enabled to build and load out-of-tree kernel modules with DKMS.

    $ uname -r
    5.XX.YY-ZZZZ.native
    

    Ensure .native or .lts is in the kernel name.

  2. Install the DKMS bundle corresponding to the installed kernel. Use kernel-native-dkms for the native kernel or kernel-lts-dkms for the lts kernel.

    sudo swupd bundle-add kernel-native-dkms
    

    or

    sudo swupd bundle-add kernel-lts-dkms
    
  3. Update the Clear Linux OS bootloader and reboot.

    sudo clr-boot-manager update
    reboot
    

Download the NVIDIA drivers

  1. Identify the NVIDIA GPU model that is installed.

    sudo lshw -C display
    
  2. Go to the NVIDIA Driver Downloads website . Search for and download the appropriate driver based on the NVIDIA GPU model you have with Linux 64-bit selected as the Operating System.

    wget https://download.nvidia.com/XFree86/Linux-x86_64/<VERSION>/NVIDIA-Linux-x86_64-<VERSION>.run
    

    If you already know the appropriate driver version for your device, you can also obtain a download link directly from one of the links below:

Disable the nouveau driver

The proprietary NVIDIA driver is incompatible with the nouveau driver and must be disabled before installation can continue.

  1. Disable the nouveau driver by creating a blacklist file under /etc/modprobe.d and reboot.

    sudo mkdir /etc/modprobe.d
    
    printf "blacklist nouveau \noptions nouveau modeset=0 \n" | sudo tee --append /etc/modprobe.d/disable-nouveau.conf
    
  2. Reboot the system and log back in. It is normal for the graphical environment not to start without the NVIDIA driver loaded.

Configure alternative software paths

The NVIDIA installer is directed to install files under /opt/nvidia as much as possible to keep its contents isolated from the rest of the Clear Linux OS system files under /usr. The dynamic linker and X server must be configured to use the content under /opt/nvidia.

  1. Configure the dynamic linker to look for and to cache shared libraries under /opt/nvidia/lib and /opt/nvidia/lib32 in addition to the default paths.

    echo "include /etc/ld.so.conf.d/*.conf" |  sudo tee --append /etc/ld.so.conf
    
    sudo mkdir /etc/ld.so.conf.d
    printf "/opt/nvidia/lib \n/opt/nvidia/lib32 \n" | sudo tee --append /etc/ld.so.conf.d/nvidia.conf
    
  2. Reload the dynamic linker run-time bindings and library cache.

    sudo ldconfig
    
  3. Create a Xorg configuration file to search for modules under /opt/nvidia in addition to the default path.

    sudo mkdir -p /etc/X11/xorg.conf.d/
    
    sudo tee /etc/X11/xorg.conf.d/nvidia-files-opt.conf > /dev/null <<'EOF'
    Section "Files"
            ModulePath      "/usr/lib64/xorg/modules"
            ModulePath      "/opt/nvidia/lib64/xorg/modules"
    EndSection
    EOF
    

Install the NVIDIA drivers

  1. A terminal not running on /dev/tty1 is useful to view uninterrupted installation progress. Switch to a secondary virtual terminal by pushing CTRL + ALT + F2 or remotely login over SSH.

  2. Navigate to the directory where the NVIDIA installer was downloaded. In this example, it was saved in the Downloads folder.

    cd ~/Downloads/
    
  3. Make the NVIDIA-Linux-x86_64-<VERSION>.run file executable.

    chmod +x NVIDIA-Linux-x86_64-<VERSION>.run
    
  4. Run the installer with the advanced options below.

    sudo ./NVIDIA-Linux-x86_64-<VERSION>.run \
    --utility-prefix=/opt/nvidia \
    --opengl-prefix=/opt/nvidia \
    --compat32-prefix=/opt/nvidia \
    --compat32-libdir=lib32 \
    --x-prefix=/opt/nvidia \
    --x-module-path=/opt/nvidia/lib64/xorg/modules \
    --x-library-path=/opt/nvidia/lib64 \
    --x-sysconfig-path=/etc/X11/xorg.conf.d \
    --documentation-prefix=/opt/nvidia \
    --application-profile-path=/etc/nvidia \
    --no-precompiled-interface \
    --no-nvidia-modprobe \
    --no-distro-scripts \
    --force-libglx-indirect \
    --glvnd-egl-config-path=/etc/glvnd/egl_vendor.d \
    --egl-external-platform-config-path=/etc/egl/egl_external_platform.d  \
    --dkms \
    --silent
    
  5. The graphical interface may automatically start after the NVIDIA driver is loaded. Return to the working terminal and log back in if necessary.

  6. Confirm that the NVIDIA kernel modules are loaded.

    lsmod | grep ^nvidia
    
  7. Run a Clear Linux OS system verification to restore files that the NVIDIA installer likely deleted.

    sudo swupd repair --quick --bundles=lib-opengl
    

    Warning

    Although a limited version of swupd repair is run above, other uses of the swupd repair command should be avoided with the proprietary NVIDIA drivers installed.

    The NVIDIA software places some files under the /usr subdirectory that are not managed by Clear Linux OS and conflict with the Clear Linux OS stateless design.

  8. Optional: Create a link for the nvidia-settings desktop entry to ~/.local/share so that it appears in the launcher for easy access.

    ln -sv /opt/nvidia/share/applications/nvidia-settings.desktop $HOME/.local/share
    

Updating

The proprietary NVIDIA drivers are installed manually outside of swupd and must be updated manually when needed.

Updating the NVIDIA drivers follows the same steps as initial installation, however the desktop environment must first be stopped so that the drivers are not in use.

  1. Follow the steps in the Download the NVIDIA drivers section to get the latest NVIDIA drivers.

  2. Temporarily set the default boot target to the multi-user, which is a non-graphical runtime.

    sudo systemctl set-default multi-user.target
    
  3. Reboot the system and log back in. It is normal for the graphical environment not to start.

  4. Follow the steps in the Install the NVIDIA Drivers section to update the NVIDIA drivers. This installation will overwrite the previous NVIDIA drivers and files.

  5. Set the default boot target back to the graphical target.

    sudo systemctl set-default graphical.target
    
  6. Reboot the system and log back in.

  7. Trigger a flatpak update that will download the runtime corresponding with the new NVIDIA drivers for the flatpak apps that require it.

    flatpak update
    

Uninstallation

The NVIDIA drivers and associated software can be uninstalled and nouveau driver restored with the instructions in this section.

  1. Remove the modprobe.d file that prevents nouveau from loading.

    sudo rm /etc/modprobe.d/disable-nouveau.conf
    
  2. Remove the xorg.conf.d file that adds a search path for X modules.

    sudo rm /etc/X11/xorg.conf.d/nvidia-files-opt.conf
    
  3. Remove the nvidia-settings desktop entry file if it was linked to ~/.local/share.

    unlink -v $HOME/.local/share/nvidia-settings.desktop
    
  4. Run the nvidia-uninstall command.

    sudo /opt/nvidia/bin/nvidia-uninstall
    
  5. Follow the prompts on the screen and reboot the system.

Troubleshooting

  • The NVIDIA driver places installer and uninstaller logs under /var/log/nvidia-install and /var/log/nvidia-uninstall.
  • NVIDIA-Linux-x86_64-<VERSION>.run --advanced-options shows many parameters to control installation behavior.
  • NVIDIA-Linux-x86_64-<VERSION>.run --extract-only extracts installation files into a directory named NVIDIA-Linux-x86_64-<VERSION>.

Brightness control

If you can’t control the screen brightness with the NVIDIA driver installed, try one of the solutions below:

  • Add a kernel parameter acpi_osi= which disables the ACPI Operating System Identification function. Some system firmware may manipulate brightness control keys based on the reported operating system. Disabling the identification mechanism can cause the system firmware to expose brightness controls that are recognizable in Linux.

    sudo mkdir -p /etc/kernel/cmdline.d
    echo "acpi_osi=" | sudo tee /etc/kernel/cmdline.d/acpi-backlight.conf
    sudo clr-boot-manager update
    
  • Add a kernel parameter for the nvidia driver: NVreg_EnableBacklightHandler=1. This handler overrides the ACPI-based one provided by the video.ko kernel module. This option is available with NVIDIA driver version 387.22 and above.

    sudo mkdir -p /etc/kernel/cmdline.d
    echo "nvidia.NVreg_EnableBacklightHandler=1" | sudo tee /etc/kernel/cmdline.d/nvidia-backlight.conf
    sudo clr-boot-manager update
    
  • Add the EnableBrightnessControl=1 options to the Device section of your xorg config. Below is an example:

    sudo mkdir -p /etc/X11/xorg.conf.d/
    
    sudo tee /etc/X11/xorg.conf.d/nvidia-brightness.conf > /dev/null <<'EOF'
    Section "Device"
        Identifier     "Device0"
        Driver         "nvidia"
        Option         "RegistryDwords" "EnableBrightnessControl=1"
    EndSection
    EOF