This can be caused by a variety of problems, such as PCI IRQ routing errors, I/O APIC problems, conflicts with other devices sharing the IRQ (or their drivers), or MSI compatibility problems.

If possible, configure your system such that your graphics card does not share its IRQ with other devices (try moving the graphics card to another slot if applicable, unload/disable the driver(s) for the device(s) sharing the card's IRQ, or remove/disable the device(s)).

Depending on the nature of the problem, one of (or a combination of) these kernel parameters might also help:

The problem may also be caused by MSI compatibility problems. See MSI Interrupts for details.

If X starts but you have trouble with OpenGL, you most likely have a problem with other libraries in the way, or there are stale symlinks. See Chapter 5, Listing of Installed Components for details. Sometimes, all it takes is to rerun ldconfig.

You should also check that the correct extensions are present;

    % xdpyinfo

should show the “GLX” and “NV-GLX” extensions present. If these two extensions are not present, then there is most likely a problem loading the glx module, or it is unable to implicitly load GLcore. Check your X config file and make sure that you are loading glx (see Chapter 6, Configuring X for the NVIDIA Driver). If your X config file is correct, then check the X log file for warnings/errors pertaining to GLX. Also check that all of the necessary symlinks are in place (refer to Chapter 5, Listing of Installed Components).

This problem occurs with DDC and "blue line" stereo glasses, that get the stereo signal from one video port of the graphics card. When a X screen does not display any stereo drawable the stereo signal is disabled on the associated video port.

Forcing stereo flipping allows the stereo glasses to shutter continuously. This can be done by enabling the OpenGL control "Force Stereo Flipping" in nvidia-settings, or by setting the X configuration option "ForceStereoFlipping" to "1".

There are two cases where this may occur. If the displays are attached to the same GPU, and one of them is out of sync with the stereo glasses, you will need to reconfigure your monitors to drive identical mode timings; see Chapter 18, Programming Modes for details.

If the displays are attached to different GPUs, the only way to synchronize stereo across the displays is with a Quadro Sync device, which is only supported by certain NVIDIA RTX/Quadro cards. See Chapter 32, Configuring Frame Lock and Genlock for details.

The kernel interface layer of the NVIDIA kernel module must be compiled specifically for the configuration and version of your kernel. If you upgrade your kernel, then the simplest solution is to reinstall the driver.

ADVANCED: You can install the NVIDIA kernel module for a non running kernel (for example: in the situation where you just built and installed a new kernel, but have not rebooted yet) with a command line such as this:

    # sh NVIDIA-Linux-x86_64-525.125.06.run --kernel-name='KERNEL_NAME'

Where 'KERNEL_NAME' is what uname -r would report if the target kernel were running.

nvidia-installer attempts to load the NVIDIA kernel module before installing the driver, and will abort if this test load fails. Similarly, if the kernel module fails to load when starting the an X server with the NVIDIA X driver, the X server will fail to start.

If the NVIDIA kernel module fails to load, you should check the output of dmesg for kernel error messages and/or attempt to load the kernel module explicitly with modprobe nvidia. There are a number of common failure cases:

You need to install the source for the Linux kernel. In most situations you can fix this problem by installing the kernel-source or kernel-devel package for your distribution

The dynamic loader on your system has a bug which will cause applications linked with pthreads, and that dlopen() libGL multiple times, to crash. This bug is present in older versions of the dynamic loader. Distributions that shipped with this loader include but are not limited to Red Hat Linux 6.2 and Mandrake Linux 7.1. Version 2.2 and later of the dynamic loader are known to work properly. If the crashing application is single threaded then setting the environment variable __GL_SINGLE_THREADED to 1 will prevent the crash. In the bash shell you would enter:

    % export __GL_SINGLE_THREADED=1

and in csh and derivatives use:

    % setenv __GL_SINGLE_THREADED 1

Previous releases of the NVIDIA Accelerated Linux Graphics Driver attempted to work around this problem. Unfortunately, the workaround caused problems with other applications and was removed after version 1.0-1541.

You are probably experiencing a problem described above. Please check the text output for the “WARNING” message described in the previous hint. Setting __GL_SINGLE_THREADED to 1 as will fix the problem.

These problems are generally caused by the build using the wrong kernel header files (i.e. header files for a different kernel version than the one you are running). The convention used to be that kernel header files should be stored in /usr/include/linux/, but that is deprecated in favor of /lib/modules/RELEASE/build/include (where RELEASE is the result of uname -r. The nvidia-installer should be able to determine the location on your system; however, if you encounter a problem you can force the build to use certain header files by using the --kernel-include-dir option. For this to work you will of course need the appropriate kernel header files installed on your system. Consult the documentation that came with your distribution; some distributions do not install the kernel header files by default, or they install headers that do not coincide properly with the kernel you are running.

You should compile the NVIDIA kernel module with the same compiler version that was used to compile your kernel. Some Linux kernel data structures are dependent on the version of gcc used to compile it; for example, in include/linux/spinlock.h:

        ...
        * Most gcc versions have a nasty bug with empty initializers.
        */
        #if (__GNUC__ > 2)
          typedef struct { } rwlock_t;
          #define RW_LOCK_UNLOCKED (rwlock_t) { }
        #else
          typedef struct { int gcc_is_buggy; } rwlock_t;
          #define RW_LOCK_UNLOCKED (rwlock_t) { 0 }
        #endif

If the kernel is compiled with gcc 2.x, but gcc 3.x is used when the kernel interface is compiled (or vice versa), the size of rwlock_t will vary, and things like ioremap will fail. To check what version of gcc was used to compile your kernel, you can examine the output of:

    % cat /proc/version

To check what version of gcc is currently in your $PATH, you can examine the output of:

    % gcc -v

Conflicting libraries may have been installed by your distribution's update utility; see Chapter 5, Listing of Installed Components for details on how to diagnose this.

Unresolved symbols are most often caused by a mismatch between your kernel sources and your running kernel. They must match for the NVIDIA kernel module to build correctly. Make sure your kernel sources are installed and configured to match your running kernel.

If your kernel is making use of the -rmap VM, the system may be leaking memory due to a memory management optimization introduced in -rmap14a. The -rmap VM has been adopted by several popular distributions, the memory leak is known to be present in some of the distribution kernels; it has been fixed in -rmap15e.

If you suspect that your system is affected, try upgrading your kernel or contact your distribution's vendor for assistance.

The installer detects the presence of an X server by checking for the X server's lock files: /tmp/.Xn-lock, where 'n' is the number of the X Display (the installer checks for X Displays 0-7). If you have exited X, but one of these files has been left behind, then you will need to manually delete the lock file. Do not remove this file if X is still running!

On some notebooks with Optimus graphics, the NVIDIA driver may not be able to retrieve the Video BIOS due to interactions between the System BIOS and the Linux kernel's ACPI subsystem. On affected notebooks, applications that require the GPU will fail, and messages like the following may appear in the system log:

NVRM: failed to copy vbios to system memory.
NVRM: RmInitAdapter failed! (0x30:0xffffffff:858)
NVRM: rm_init_adapter(0) failed

Such problems are typically beyond the control of the NVIDIA driver, which relies on proper cooperation of ACPI and the System BIOS to retrieve important information about the GPU, including the Video BIOS.

Release 361 of the NVIDIA Linux driver introduced OpenGL libraries built upon the libglvnd (GL Vendor Neutral Dispatch) architecture, to allow for the coexistence of multiple OpenGL implementations on the same system. Beginning with release 364, the GLVND libraries are installed by default.

By design, GLVND conforms with the Linux OpenGL ABI version 1.0 as defined at https://www.opengl.org/registry/ABI/ and exposes all required entry points; however, applications which depend upon specifics of the NVIDIA OpenGL implementation which fall outside of the OpenGL ABI may be incompatible with a GLVND-based OpenGL implementation.

If you encounter an application which is incompatible with GLVND, please contact the application vendor to inform them that their application will need to be updated to ensure compatibility with GLVND.

Resizing a Vulkan application generates events that trigger an out-of-date swapchain.

Fullscreen Vulkan applications are optimized for performance by the driver. This optimization also generates events that trigger an out-of-date swapchain upon entering or leaving fullscreen mode. This is commonly encountered when using the alt-tab key combination, for example.

Applications that do not properly respond to the VK_ERROR_OUT_OF_DATE_KHR return code may not function properly when these events occur. The expected behavior is documented in section 30.8 of the Vulkan specification.

By default, nvidia-installer creates a /etc/vulkan/icd.d/nvidia_icd.json that points to libGLX_nvidia.so.0. This DSO has dependencies on X libraries.

It is possible to avoid those dependencies by hand editing that file to point to libEGL_nvidia.so.0 instead. However in that case, an application will only be able to create non-X swapchains if it wants to present frames.

The Vulkan application may be choosing your iGPU instead of your NVIDIA dGPU. Starting with the 435 driver series, you can set the following environment variable to force the Vulkan loader to list NVIDIA GPUs before other devices:

__NV_PRIME_RENDER_OFFLOAD=1

This can be used even if the system is not otherwise configured to use Chapter 35, PRIME Render Offload.

In order to prefer discrete GPUs over integrated GPUs, application developers can check the VkPhysicalDeviceProperties::deviceType field when querying available physical devices.

The application is probably using a different library that still remains on your system, rather than the NVIDIA supplied OpenGL library. See Chapter 5, Listing of Installed Components for details.

Incorrectly sized fonts are generally caused by incorrect DPI (Dots Per Inch) information. You can check what X thinks the physical size of your monitor is, by running:

 % xdpyinfo | grep dimensions

This will report the size in pixels, and in millimeters.

If these numbers are wrong, you can correct them by modifying the X server's DPI setting. See Appendix E, Dots Per Inch for details.

The NVIDIA OpenGL driver must be able to map anonymous memory with read and write execute privileges in order to function correctly. The driver needs this ability to allocate aligned memory, which is used for certain optimizations. Currently, GLX cannot run without these optimizations.

This indicates that the X driver was not able to put the GPU in interactive mode, because another program has requested non-interactive mode. The GPU watchdog will not run, and long-running GPU compute programs may cause the X server and OpenGL programs to hang. If you intend to run long-running GPU compute programs, set the Interactive option to "off" to disable interactive mode.

Installation or configuration problems may prevent the X server, a login/session manager, or a desktop environment from starting correctly. If your system is failing to display a login screen, or failing to start a desktop session, try the following troubleshooting steps:

Depending on the type of configuration being performed, nvidia-settings will save configuration changes to one of several places:

Settings in ~/.nvidia-settings-rc only take effect when processed by nvidia-settings, and therefore will not be loaded by default when starting a new X session. To load settings from ~/.nvidia-settings-rc without actually opening the nvidia-settings control panel, use the --load-config-only option on the nvidia-settings command line. nvidia-settings --load-config-only can be added to your login scripts to ensure that your settings are restored when starting a new desktop session.

Even after nvidia-settings has been run to restore any settings set in ~/.nvidia-settings-rc, some desktop environments (e.g. GNOME, KDE, Unity, Xfce) include advanced display configuration tools that may override settings that were configured via nvidia-settings. These tools may attempt to restore their own display configuration when starting a new desktop session, or when events such as display hotplugs, resolution changes, or VT switches occur.

These tools may also override some types of settings that are stored in and loaded from the X configuration file, such as any MetaMode strings that may specify the initial display layouts of NVIDIA X screens. Although the configuration of the initial MetaMode is static, it is possible to dynamically switch to a different MetaMode after X has started. This can have the effect of making the set of active displays, their resolutions, and layout positions as configured in the nvidia-settings control panel appear to be ineffective, when in reality, this configuration was active when starting X and then overridden later by the desktop environment.

If you believe that your desktop environment is overriding settings that you configured in nvidia-settings, some possible solutions are:

Some systems may have multiple different display configuration utilities, each with its own way of managing settings. In addition to conflicting with nvidia-settings, such tools may conflict with each other. If your system uses more than one tool for configuring displays, make sure to check the configuration of each tool when attempting to determine the source of any unexpected display settings.

This is a special case of the issues described in “The display settings I configured in nvidia-settings do not persist.”. Some desktop environments which include advanced display configuration tools will automatically configure the display layout in response to detected configuration changes. For example, when a new display is plugged in, such a desktop environment may attempt to restore the previous layout that was used with the set of currently connected displays, or may configure a default layout based upon its own policy.

On X servers with support for RandR 1.2 or later, the NVIDIA X driver reports display hotplug events to the X server via RandR when displays are connected and disconnected. These hotplug events may trigger a desktop environment with advanced display management capabilities to change the display configuration. These changes may affect settings such as the set of active displays, their resolutions and positioning relative to each other, per-display color correction settings, and more.

In addition to hotplug events generated by connecting or disconnecting displays, DisplayPort displays will generate a hot unplug event when they power off, and a hotplug event when they power on, even if no physical plugging in or unplugging takes place. This can lead to hotplug-induced display configuration changes without any actual hotplug action taking place.

Upon suspend, the NVIDIA X driver will incur an implicit VT switch. If a DisplayPort monitor is powered off when a VT switch or modeset occurs, RandR will forget the configuration of that monitor. As a result, the display will be left without a mode once powered back on. In the absence of an RandR-aware window manager, bringing back the display will require manually configuring it with RandR.

If display hotplug events are resulting in undesired configuration changes, try the solutions and workarounds listed in “The display settings I configured in nvidia-settings do not persist.”. Another workaround would be to disable the NVIDIA X driver's reporting of hotplug events with the UseHotplugEvents X configuration option. Note that this option will have no effect on DisplayPort devices, which must report all hotplug events to ensure proper functionality.

Some desktop environments or window managers might not function correctly if no displays are exposed via the RandR API. When the NVIDIA X driver is configured for headless operation, either with 'Option "AllowEmptyInitialConfiguration"' and no connected displays, with 'Option "MetaModes" "NULL"', or with 'Option "UseDisplayDevice" "none"', it will not expose any displays via RandR.

To work around software that requires RandR displays on a machine that is only intended to be used remotely, you can connect a physical display, or configure the X driver to behave as if a physical display were connected using the "ConnectedMonitor" option. See Appendix B, X Config Options for additional information about the "ConnectedMonitor" option.

Nouveau is a display driver for NVIDIA GPUs, developed as an open-source project through reverse-engineering of the NVIDIA driver. It ships with many current Linux distributions as the default display driver for NVIDIA hardware. It is not developed or supported by NVIDIA, and is not related to the NVIDIA driver, other than the fact that both Nouveau and the NVIDIA driver are capable of driving NVIDIA GPUs. Only one driver can control a GPU at a time, so if a GPU is being driven by the Nouveau driver, Nouveau must be disabled before installing the NVIDIA driver.

Nouveau performs modesets in the kernel. This can make disabling Nouveau difficult, as the kernel modeset is used to display a framebuffer console, which means that Nouveau will be in use even if X is not running. As long as Nouveau is in use, its kernel module cannot be unloaded, which will prevent the NVIDIA kernel module from loading. It is therefore important to make sure that Nouveau's kernel modesetting is disabled before installing the NVIDIA driver.

A simple way to prevent Nouveau from loading and performing a kernel modeset is to add configuration directives for the module loader to a file in one of the system's module loader configuration directories: for example, /etc/modprobe.d/ or /usr/local/modprobe.d. These configuration directives can technically be added to any file in these directories, but many of the existing files in these directories are provided and maintained by your distributor, which may from time to time provide updated configuration files which could conflict with your changes. Therefore, it is recommended to create a new file, for example, /etc/modprobe.d/disable-nouveau.conf, rather than editing one of the existing files, such as the popular /etc/modprobe.d/blacklist.conf. Note that some module loaders will only look for configuration directives in files whose names end with .conf, so if you are creating a new file, make sure its name ends with .conf.

Whether you choose to create a new file or edit an existing one, the following two lines will need to be added:

blacklist nouveau
options nouveau modeset=0

The first line will prevent Nouveau's kernel module from loading automatically at boot. It will not prevent manual loading of the module, and it will not prevent the X server from loading the kernel module; see "How do I prevent the X server from loading Nouveau?" below. The second line will prevent Nouveau from doing a kernel modeset. Without the kernel modeset, it is possible to unload Nouveau's kernel module, in the event that it is accidentally or intentionally loaded.

You will need to reboot your system after adding these configuration directives in order for them to take effect.

If nvidia-installer detects Nouveau is in use by the system, it will offer to create such a modprobe configuration file to disable Nouveau.

Some distributions include Nouveau in an initial ramdisk image (henceforth referred to as "initrd" in this document, and sometimes also known as "initramfs"), so that Nouveau's kernel modeset can take place as early as possible in the boot process. This poses an additional challenge to those who wish to prevent the modeset from occurring, as the modeset will occur while the system is executing within the initrd, before any directives in the module loader configuration files are processed.

If you have an initrd which loads the Nouveau driver, you will additionally need to ensure that Nouveau is disabled in the initrd. In most cases, rebuilding the initrd will pick up the module loader configuration files, including any which may disable Nouveau. Please consult your distribution's documentation on how to rebuild the initrd, as different distributions have different tools for building and modifying the initrd. Some popular distro initrd tools include: dracut, mkinitrd, and update-initramfs.

Some initrds understand the rdblacklist parameter. On these initrds, as an alternative to rebuilding the initrd, you can add the option rdblacklist=nouveau to your kernel's boot parameters. On initrds that do not support rdblacklist, it is possible to prevent Nouveau from performing a kernel modeset by adding the option nouveau.modeset=0 to your kernel's boot parameters. Note that nouveau.modeset=0 will prevent a kernel modeset, but it may not prevent Nouveau from being loaded, so rebuilding the initrd or using rdblacklist may be more effective than using nouveau.modeset=0.

Any changes to the default kernel boot parameters should be made in your bootloader's configuration file(s), so that the options get passed to your kernel every time the system is booted. Please consult your distribution's documentation on how to configure your bootloader, as different distributions use different bootloaders and configuration files.

Blacklisting Nouveau will only prevent it from being loaded automatically at boot. If an X server is started as part of the normal boot process, and that X server uses the Nouveau X driver, then the Nouveau kernel module will still be loaded. Should this happen, you will be able to unload Nouveau with `modprobe -r nouveau` after stopping the X server, as long as you have taken care to prevent it from doing a kernel modeset; however, it is probably better to just make sure that X does not load Nouveau in the first place.

If your system is not configured to start an X server at boot, then you can simply run the NVIDIA driver installer after rebooting. Otherwise, the easiest thing to do is to edit your X server's configuration file so that your X server uses a non-modesetting driver that is compatible with your card, such as the vesa driver. You can then stop X and install the driver as usual. Please consult your X server's documentation to determine where your X server configuration file is located.