From Gentoo Wiki
Jump to: navigation, search
This page contains changes which are not marked for translation.

Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎italiano • ‎日本語 • ‎한국어 • ‎Nederlands • ‎русский • ‎中文(中国大陆)‎

x11-drivers/nvidia-drivers is the proprietary graphics driver for nVidia graphic cards. An open source alternative is nouveau.

The x11-drivers/nvidia-drivers in the tree are released by nVidia and are built against the Linux kernel. They contain a binary blob that does the heavy lifting for talking to the card. The drivers consist of two parts, a kernel module, and an X11 driver. Both parts are included in a single package. Due to the way nVidia has been packaging their drivers, it is necessary to make some choices before installing the drivers.

The x11-drivers/nvidia-drivers package contains the latest drivers from nVidia with support for all cards, with several versions available depending on how old the card is. It uses an eclass to detect what kind of card the system is running so that it installs the proper version.

Hardware compatibility

The x11-drivers/nvidia-drivers package supports a range of available nVidia cards. Multiple versions are available for installation, depending on the card(s) that the system has. See the official nVidia documentation, What's a legacy driver?, to find out what version of x11-drivers/nvidia-drivers should be used. A pretty decent way to find this out through an interactive form. Enter the graphics card that is used by the system (mind the Legacy option in the 'Product Type' field) and the form should end up with the best supported version.

If the card has been identified as a legacy card then mask the more recent releases of nvidia-drivers, i.e

FILE /etc/portage/package.maskMasking drivers with version higher than 174

Note that Gentoo does not provide the 71.86.xx versions. If the system has a card that needs these drivers then it is recommended to use the nouveau driver.



As mentioned above, the nVidia kernel driver installs and runs against the current kernel. It builds as a module, so the kernel must support the loading of kernel modules (see below).

The kernel module (nvidia.ko) consists of a proprietary part (commonly known as the "binary blob") which drives the graphics chip(s), and an open source part (the "glue") which at runtime acts as intermediary between the proprietary part and the kernel. These all need to work nicely together as otherwise the user might be faced with data loss (through kernel panics, X servers crashing with unsaved data in X applications) and even hardware failure (overheating and other power management related issues should spring to mind).

Kernel compatibility

From time to time, a new kernel release changes the internal ABI for drivers, which means all drivers that use those ABIs must be changed accordingly. For open source drivers, especially those distributed with the kernel, these changes are nearly trivial to fix since the entire chain of calls between drivers and other parts of the kernel can be reviewed quite easily. For proprietary drivers like nvidia.ko, it doesn't work quite the same. When the internal ABIs change, then it is not possible to merely fix the "glue", because nobody knows how the glue is used by the proprietary part. Even after managing to patch things up to have things seem to work nicely, the user still risks that running nvidia.ko in the new, unsupported kernel will lead to data loss and hardware failure.

When a new, incompatible kernel version is released, it is probably best to stick with the newest supported kernel for a while. Nvidia usually takes a few weeks to prepare a new proprietary release they think is fit for general use. Just be patient. If absolutely necessary, then it is possible to use the epatch_user command with the nvidia-drivers ebuilds: this allows the user to patch nvidia-drivers to somehow fit in with the latest, unsupported kernel release. Do note that neither the nvidia-drivers maintainers nor Nvidia will support this situation. The hardware warranty will most likely be void, Gentoo's maintainers cannot begin to fix the issues since it's a proprietary driver that only Nvidia can properly debug, and the kernel maintainers (both Gentoo's and upstream) will certainly not support proprietary drivers, or indeed any "tainted" system that happens to run into trouble.

If genkernel all was used to configure the kernel, then everything is all set. If not, double check the kernel configuration so that this support is enabled:

KERNEL Enable loadable module support
[*] Enable loadable module support --->

Also enable Memory Type Range Register in the kernel:

KERNEL Enable MTRR support
Processor type and features --->
   [*] MTRR (Memory Type Range Register) support

If the system has an AGP graphics card, then optionally enable agpgart support to the kernel, either compiled in or as a module. If the in-kernel agpgart module is not used, then the drivers will use its own agpgart implementation, called NvAGP. On certain systems, this performs better than the in-kernel agpgart, and on others, it performs worse. Evaluate either choice on the system to get the best performance. When uncertain what to do, use the in-kernel agpgart:

KERNEL Enable agpgart support
Device Drivers --->
   Graphics support --->
      -*- /dev/agpgart (AGP Support) --->
On amd64, the IOMMU controls the agpgart setting.
For x86 and AMD64 processors, the in-kernel framebuffer driver conflicts with the binary driver provided by nVidia. When compiling the kernel for these CPUs, completely remove support for the in-kernel driver as shown:
KERNEL Disable support for the in-kernel driver
Device Drivers --->
    Graphics support --->
        Frame buffer Devices --->
            <*> Support for frame buffer devices --->
            < >   nVidia Framebuffer Support
            < >   nVidia Riva support

Now make sure the nouveau driver is disabled:

Device Drivers  --->
    Graphics support  --->
        < > Nouveau (nVidia) cards

A framebuffer alternative is uvesafb, which can be installed parallel to x11-drivers/nvidia-drivers.

For x86 and AMD64 processors, the uvesafb driver conflicts with the binary driver provided by nVidia above 361.28 versions.

For (U)EFI systems, uvesafb will not work. Be warned that enabling efifb support in kernel (CONFIG_FB_EFI=y) causes intermittent problems with the initialization of the nvidia drivers. There is no known alternative framebuffer for (U)EFI systems.

The nvidia-drivers ebuild automatically discovers the kernel version based on the /usr/src/linux symlink. Please ensure that this symlink is pointing to the correct sources and that the kernel is correctly configured. Please refer to the "Configuring the Kernel" section of the Gentoo Handbook for details on configuring the kernel.

First, choose the right kernel source using eselect. When using sys-kernel/gentoo-sources version 3.7.10 for instance, the kernel listing might look something like this:

root #eselect kernel list
Available kernel symlink targets:
  [1]   linux-3.7.10-gentoo *
  [2]   linux-3.7.9-gentoo

In the above output, notice that the linux-3.7.10-gentoo kernel is marked with an asterisk (*) to show that it is the symlinked kernel.

If the symlink is not pointing to the correct sources, update the link by selecting the number of the desired kernel sources, as in the example above.

root #eselect kernel set 1



Now it's time to install the drivers. First follow the X Server Configuration Guide and set VIDEO_CARDS="nvidia" in /etc/portage/make.conf. During the installation of the X server, it will then install the right version of x11-drivers/nvidia-drivers.

The drivers can be installed with the gtk USE flag set in /etc/portage/make.conf. This will install media-video/nvidia-settings, a handy graphical tool for monitoring and configuring several aspects of the nVidia card.
Every time a kernel is built, it is necessary to reinstall the nVidia kernel modules. An easy way to rebuild the modules installed by ebuilds (such as x11-drivers/nvidia-drivers) is to run emerge @module-rebuild.

Once the installation has finished, run modprobe nvidia to load the kernel module into memory. If this is an upgrade, remove the previous module first.

root #lsmod | grep nvidia
root #rmmod nvidia
root #modprobe nvidia

To prevent from having to manually load the module on every bootup, have this done automatically each time the system is booted, so edit /etc/conf.d/modules and add nvidia to it.

If agpgart is compiled as a module, then add it to /etc/conf.d/modules as well.

Kernel module signing (optional)

The information in this section in unnecessary for systems that do not implement signed kernel modules. Feel free to skip it.

If you are using secure boot kernel signing then you will need to sign the Nvidia kernel modules before they can be loaded.

You do this by using the kernel provided perl script as follows.

root #perl /usr/src/linux/scripts/sign-file sha512 /usr/src/linux/signing_key.priv /usr/src/linux/signing_key.x509 /lib/modules/Kernel-Version-modules-path/video/nvidia-uvm.ko
root #perl /usr/src/linux/scripts/sign-file sha512 /usr/src/linux/signing_key.priv /usr/src/linux/signing_key.x509 /lib/modules/Kernel-Version-modules-path/video/nvidia.ko

As of driver version 358.09 a new module has been made to handle monitor mode setting and for this driver version this module must also be signed.

root #perl /usr/src/linux/scripts/sign-file sha512 /usr/src/linux/signing_key.priv /usr/src/linux/signing_key.x509 /lib/modules/Kernel-Version-modules-path/video/nvidia-modeset.ko

Once you have signed these modules then the driver will load as expected on boot up. This module signing method can be used to sign other modules not only your nvidia-drivers. You would have to modify the path and corresponding module accordingly.

The X server

Once the appropriate drivers are installed, configure the X server to use the nvidia driver instead of the default nv driver.

FILE /etc/X11/xorg.conf.d/nvidia.confExplicit nvidia driver section
 Section "Device"
   Identifier  "nvidia"
   Driver      "nvidia"

Run eselect so that the X server uses the nVidia GLX libraries:

root #eselect opengl set nvidia


You will need to add the user you want to be able to access the video card to the video group:

root #gpasswd -a larry video

Note that you will still be able to run X without permission to the DRI subsystem, but usually not with acceleration enabled.

Enabling global nvidia support

Some tools, such as media-video/mplayer and media-libs/xine-lib, use a local USE flag called xvmc which enables XvMCNVIDIA support, useful when watching high resolution movies. Add in xvmc in the USE variable in /etc/portage/make.conf or add it as USE flag to media-video/mplayer and/or media-libs/xine-lib in /etc/portage/package.use.

GeForce 8 series and later GPUs do come with VDPAU support which superseded XvMCNVIDIA support. See the VDPAU article for enabling VDPAU support.

There are also some applications that use the nvidia USE flag, so it might be a good idea to add it to /etc/portage/make.conf.

Then, run emerge -uD --newuse @world to rebuild the applications that benefit from the USE flag change.

Using the nVidia settings tool

nVidia also provides a settings tool. This tool allows the user to monitor and change graphical settings without restarting the X server and is available through Portage as media-video/nvidia-settings. As mentioned earlier, it will be pulled in automatically when installing the drivers with the gtk USE flag set in /etc/portage/make.conf or in /etc/portage/package.use.

Enable OpenGL/OpenCL

To enable OpenGL and OpenCL though the device, run:

root #eselect opengl set nvidia
root #eselect opencl set nvidia

Make sure that the Xorg server is not running during these changes.


Testing the card

To test the nVidia card, fire up X and run glxinfo, which is part of the x11-apps/mesa-progs package. It should say that direct rendering is activated:

user $glxinfo | grep direct
direct rendering: Yes

To monitor the FPS, run glxgears.


Driver fails to initialize when MSI interrupts are enabled

The Linux NVIDIA driver uses Message Signaled Interrupts (MSI) by default. This provides compatibility and scalability benefits, mainly due to the avoidance of IRQ sharing. Some systems have been seen to have problems supporting MSI, while working fine with virtual wire interrupts. These problems manifest as an inability to start X with the NVIDIA driver, or CUDA initialization failures.

MSI interrupts can be disabled via the NVIDIA kernel module parameter NVreg_EnableMSI=0. This can be set on the command line when loading the module, or more appropriately via the distribution's kernel module configuration files (such as those under /etc/modprobe.d/).

For instance:

FILE /etc/modprobe.d/nvidia.confSetting nvidia NVreg_EnableMSI
# Nvidia drivers support
alias char-major-195 nvidia
alias /dev/nvidiactl char-major-195
# To tweak the driver the following options can be used, note that
# you should be careful, as it could cause instability!! For more 
# options see /usr/share/doc/nvidia-drivers-337.19/README 
options nvidia NVreg_DeviceFileMode=432 NVreg_DeviceFileUID=0 NVreg_DeviceFileGID=27 NVreg_ModifyDeviceFiles=1 NVreg_EnableMSI=0

Getting 2D acceleration to work on machines with 4GB memory or more

When nVidia 2D acceleration is giving problems, then it is likely that the system is unable to set up a write-combining range with MTRR. To verify, check the contents of /proc/mtrr:

root #cat /proc/mtrr

Every line should contain write-back or write-combining. When a line shows up with uncachable in it then it is necessary to change a BIOS setting to fix this.

Reboot and enter the BIOS, then find the MTRR settings (probably under "CPU Settings"). Change the setting from continuous to discrete and boot back into Linux. There is now no uncachable entry anymore and 2D acceleration now works without any glitches.

"no such device" appears when trying to load the kernel module

This is usually caused by one of the following issues:

  1. The system does not have a nVidia card at all. Check lspci output to confirm that the system has a nVidia graphics card installed and detected.
  2. The currently installed version of x11-drivers/nvidia-drivers does not support the installed graphics card model. Check the README file in /usr/share/nvidia-drivers-*/ for a list of supported devices, or use the driver search at http://www.geforce.com/drivers.
  3. Another kernel driver has control of the hardware. Check lspci -k to see if another driver like "nouveau" is bound to the graphics card. If so, disable or blacklist this driver.

Xorg says it can't find any screens

When after booting the system, it ends up with a black screen or a console prompt instead of the GUI; then press Ctrl+Alt+F2 to bring up a virtual console. Next, run:

root # /etc/init.d/xdm stop
user $ startx

to see the output of Xorg. If one of the first errors is that Xorg can't find any screens, then follow the following steps to resolve the issue.

It should be enough to run the following command before rebooting:

root #/opt/bin/nvidia-xconfig

But if that doesn't work, run lspci and notice that the video card starts off like this:

root #lspci
 . . .
01:00.0 VGA compatible controller: make and model of videocard
 . . . 

Take the first bit, 01.00.0 and put it in the /etc/X11/xorg.conf file with the BusID option:

FILE /etc/X11/xorg.conf
# this is not the whole file, only the part that needs edited
# the file should already exist after running nvidia-xconfig
Section "Device"
    Identifier     "Device0"
    Driver         "nvidia"
    VendorName     "NVIDIA Corporation"
    BusID          "PCI:1:0:0"

Direct rendering is not enabled

If direct rendering does not work, it may be because the kernel has Direct Rendering Manager enabled, which conflicts with the driver. See the direct rendering status by following instructions in the section Testing the card.

First, disable Direct Rendering Manager (CONFIG_DRM) in the kernel :

KERNEL Disabling Direct Rendering Manager
Device drivers --->
    Graphics support --->
        < > Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)

Next, rebuild x11-drivers/nvidia-drivers since the driver may have built against the kernel DRM symbols. It should fix the problem.

Video playback stuttering or slow

Lately there seems to be some breaking with playback of some types of video with the NVidia binary drivers, causing slow video playback or significant stuttering. This problem seems to be occurring within the Intel CPU Idle replacement instead of the common ACPI CPU idling method for certain CPU's.

Disable the Intel CPU idling method using intel_idle.max_cstate=0 on the kernel command line boot method, which should cause the kernel to automatically fall back to the normal or older ACPI CPU idling method. Also, disabling the NVidia Powermizer feature, or setting Powermizer to maximum performance within nvidia-settings has been said to help. Although the Intel CPU idling method recently was introduced as the default CPU idling method for i5 and i7 CPUs (versus using ACPI CPU idling) is the root cause here. This idling method significantly solves the problem, however some minimal stuttering or slow video is encountered if deinterlacing was enabled; this is when the video is likely already deinterlaced (ie. alias mplayer-nodeint with something similar to mplayer -vo vdpau:deint=0:denoise=0:nochroma-deint:colorspace=0:hqscaling=1, video.mpg as a work around.)

No vertical synchronization (no VSync, tearing) in OpenGL applications

Adding the following option to the screen section prevents tearing on GTX 660, 660 Ti, and probably some other GPUs (reference):

FILE /etc/X11/xorg.conf
Section "Section"
     . . .
    Option         "metamodes" "nvidia-auto-select +0+0 { ForceFullCompositionPipeline = On }"
     . . .

Expert configuration


The x11-drivers/nvidia-drivers package also comes with comprehensive documentation. This is installed into /usr/share/doc and can be viewed with the following command:

user $less /usr/share/doc/nvidia-drivers-*/README.bz2

Kernel module parameters

The nvidia kernel module accepts a number of parameters (options) which can be used to tweak the behaviour of the driver. Most of these are mentioned in the documentation. To add or change the values of these parameters, edit the file /etc/modprobe.d/nvidia.conf. Remember to run update-modules after modifying this file, and bear in mind to reload the nvidia module before the new settings take effect.

To tweak the driver the following options can be used, note that
you should be careful, as it could cause instability!! For more 
options see /usr/share/doc/nvidia-drivers-361.28/README 

It is very important to pay attention to this section as these kernel options can enable features your hardware may or may-not support so you must know exactly what you are doing. These options are not forgiving.

Attribute Description
NVreg_DeviceFileUID=0 This allows you to modify the user ID device file permission, 0 = root by default. Setting this to another user ID will only allow the driver module to create the device file access available to that user ID you select.
NVreg_DeviceFileGID=27 Much the same as the user ID this sets the Group ID for the device file. By default it is set to 27 = Video group ID but can be changed.
NVreg_DeviceFileMode=432 This is the permissions granted to the user ID, Group ID and others, changing these permissions to other setting such as 0660 from the default 0432 could cause serious security risks. Best to leave as default but you have the option to change it if you wish.
NVreg_ModifyDeviceFiles=1 This option is enabled by default and is boolean (either 0 = disabled or 1 = enabled). This instructs the driver to allow the device files created and permission for UserID and GroupID respecting DeviceFileMode to be modified as needed. Device files are those mounted in /dev just the same as disk drives are listed as /dev/sdx and so on. Your graphics card driver has a device file just the same.
NVreg_EnablePCIeGen3=1 This does exactly as it says, it enables PCIe Gen 3.x support. If your system supports this 8GT high speed bus then you can enable it with this module option flag. If you enable this and you do not have Gen 3.0 support in your computer then you will most likely see irratic and unstable behavior. Some have even reported damage to hardware enabling this when it is not properly supported. By default the Nvidia driver is set to use PCIe Gen 2.x for compatibility reasons.
NVreg_UsePageAttributeTable=1 This is one of the latest and newest additions to the Nvidia driver modules option. It allows the driver to take full advantage of the PAT technology that is the newer way of allocating memory and is to replace the older MTRR(Memory Type Range Register) method. The PAT method creates a Partition type table at specific addresses mapped inside the register and utilises the memory architecture and instruction set more efficiently and faster. If your computer supports PAT and you have enabled it in your Kernel then this flag can be enabled. If you don't have PAT support you may experience unstable performance, crashing even failure enabling this so be careful with these options.
NVreg_EnableVia4x=0 For those using the Nvidia driver for AGP card in a system using the Via chipset. Some of these hardware configurations would not work properly in AGP 4x mode when other would. You can use this option to set it to 4x mode to see if your AGP bus speed will work, if not set to disabled and leave it be at 2x.
NVreg_EnableALiAGP=0 Much like the above setting this allows you to set a specific bit-rate. This is NOT a boolean setting. The settings are 1,2,4 and 8 referring to AGP 1x, 2x, 4x, and 8x. Setting this or changing the automatic negotiation of the AGP speed is not recommended by Nvidia as it can cause problems. This setting again carries with it WARNINGS if used.
NVreg_ReqAGPRate=0 Again much like the above setting this allows you to set a specific bit-rate. This is NOT a boolean setting. The settings are 1,2,4 and 8 referring to AGP 1x, 2x, 4x, and 8x. Setting this or changing the automatic negotiation of the AGP speed is not recommended by Nvidia as it can cause problems. This setting again carries with it WARNINGS if used.
NVreg_NvAGP=0 This is the AGP Gart mode setting. This allows you to 0 = Disable, 1 = Enable the use of Nvidias internal AGP-Gart, 2 = Enable and use the Linux Kernels AGP-Gart and 3 = Enable and use any available AGP_Gart trying the Nvidia built in first.
NVreg_EnableAGPSBA=0 AGP Side Banding. This is a boolean 0 = Disabled and 1 = Enabled. The default is Disabled for stability reasons but you could enable this for testing and debugging purposes. This is not supported again by Nvidia so you enable this at your own risk.
NVreg_EnableAGPFW AGP Fast-Writes, this is disabled by default but can be enabled to allow for faster data writes. Depending on your systems chipset this may cause stability issues if enabled. 0 = Disabled 1 = Enabled.
NVreg_Mobile=0 This option is provided for mobile GPU's where EDID information is either non-functional or disabled. 0 = Auto detection of the correct setting, 1= Dell notebooks, 2 = non-compa1 Toshiba laptops, 3 = All other notebooks/laptops, 4 = Compa1 Toshiba laptops, 5 = Gateway machines.
NVreg_RemapLimit=60 Maximum amount of system memory remapping. You can specify an amount of memory here depending on your hardware to which the driver will be allowed to remap through the IOMMU/SWIOTLB on a 64Bit system particularly. If the IOMMU or SMIOTLB is larger than 64mb on your system then Nvidia have put this feature in here to allow you the ability to teak this value. They recommend you subtract 4mb away from the amount you wish to use. For instance the default value is 60mb which is in fact 64mb - 4 = 60 so the value set is 60. If you wish to set it to 128mb then again subtract 4mb and set the value to 124mb. This is a tweak setting so there is no way of knowing what will work best for your application only that 64mb(60) is stable across the majority of systems.
NVreg_UpdateMemoryTypes=0 Due to kernels broken implementations across the board Nvidia has provided this option to change the page attributes. On some versions of kernels the Nvidia driver has to do things very carefully in not using these attributes in the PAT the driver allows you to override the drivers default logic mechanism in deciding what tables to write-cache and write-back etc. You can ether 0 = Nvidias logic mechanism, 1 = Enable the use of change page table attributes or 2 = Disable the use of page table attributes. The default (0) setting will cause the driver to automatically detect if it can safely use the memory mappings.
NVreg_InitializeSystemMemoryAllocations=1 Instruct to clear the system memory allocations for use with GPU's. This allows you to disable this functionality for performance boost but at the cost of security vulnerability. By default the driver will wipe clear the memory allocations by zeroing out contents within it. As with all computing functions these take time so if you wish to wade this function you can do.
NVreg_UseVBios=1 Option to enable or disable the use of the Vedio BIOS int10 code. Default is 1 = Enabled. To Disable set to 0.
NVreg_RMEdgeIntrCheck=1 Edge-triggered-interupt-check. This is a boolean value to enable or disable the driver checking this.
NVreg_EnableMSI=0 PCIe-MSI capabilities can be 1 = enabled or 0 = disabled, the default setting is disabled MSI Interrupts. You can enable this if you wish to use MSI-Interrupts instead of Wired-Interrupts.
NVreg_MapRegistersEarly=0 this setting allows the driver to map the memory locations early when the system is probing the hardware instead of the default option of doing this when loaded by modprobe or during startx. This is a Debugging feature but may have further uses, who knows.
NVreg_RegisterForACPIEvents=1 By default the option is 1 = Enabled and the driver will register with the ACPI of the system to receive ACPI events> you can disable this if you are having issues with your ACPI or you are debugging an issue.

Edit /etc/modprobe.d/nvidia.conf:

root #nano -w /etc/modprobe.d/nvidia.conf
FILE /et/modprove.d/nvidia.confNvidia.conf
# Nvidia drivers support
alias char-major-195 nvidia
alias /dev/nvidiactl char-major-195

# To tweak the driver the following options can be used, note that
# you should be careful, as it could cause instability!! For more 
# options see /usr/share/doc/nvidia-drivers-361.28/README 
options nvidia NVreg_DeviceFileMode=432 NVreg_DeviceFileUID=0 NVreg_DeviceFileGID=27 NVreg_ModifyDeviceFiles=1 NVreg_EnablePCIeGen3=1 NVreg_UsePageAttributeTable=1

Update module information:

root #update-modules

Unload the nvidia module...

root #modprobe -r nvidia

...and load it once again:

root #modprobe nvidia

Advanced X configuration

The GLX layer also has a plethora of options which can be configured. These control the configuration of TV out, dual displays, monitor frequency detection, etc. Again, all of the available options are detailed in the documentation.

To use any of these options, list them in the relevant Device section of the X config file (usually /etc/X11/xorg.conf). For example, to disable the splash logo:

FILE /etc/X11/xorg.confDisable the splash logo
Section "Device"
  Identifier "nVidia Inc. GeForce2"
  Driver     "nvidia"
  Option     "NoLogo" "true"
  VideoRam   65536

See also

This article is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Sven Vermeulen, Joshua Saddler, M Curtis Napier and Chris Gianelloni
They are listed here as the Wiki history does not allow for any external attribution. If you edit the Wiki article, please do not add yourself here; your contributions are recorded on the history page.