From Gentoo Wiki
Jump to: navigation, search
This page is a translated version of the page NVIDIA/nvidia-drivers and the translation is 46% complete.

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


x11-drivers/nvidia-drivers 在树中被发布的 NVDIA是针对 Linux 内核构建的。它们包含二进制数据, 和驱动的重任。驱动程序包括两个部分,一个内核模块和 X11 的驱动程序。两个部分都包含在一个包中。由于 NVDIA有他们自己的驱动包 ,就必须在安装的驱动程序做出一些选择。


USE flags

USE flags for x11-drivers/nvidia-drivers NVIDIA Accelerated Graphics Driver

X Install the X.org driver, OpenGL libraries, XvMC libraries, and VDPAU libraries
acpi Add support for Advanced Configuration and Power Interface
compat Install non-GLVND libGL for backwards compatibility
driver Install the kernel driver module
gtk3 Install nvidia-settings with support for GTK+ 3
kms Enable support for kernel mode setting (KMS)
libglvnd Use media-libs/libglvnd for dispatch
multilib On 64bit systems, if you want to be able to compile 32bit and 64bit binaries
static !!do not set this during bootstrap!! Causes binaries to be statically linked instead of dynamically
static-libs Build static versions of dynamic libraries as well
tools Install additional tools such as nvidia-settings
uvm Install the Unified Memory kernel module (nvidia-uvm) for sharing memory between CPU and GPU in CUDA programs
wayland Enable dev-libs/wayland backend


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.

Legacy hardware

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

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.




内核模块 (nvidia.ko)由一个专有部分(通常称为“二进制blob)驱动图形芯片,和一个开源部分(“glue”),在运行时作为专有部分和内核之间的媒介。这些都需要很好地协同工作,否则用户可能面临数据丢失(通过内核panics, X servers崩溃伴随着未保存数据X的应用程序),甚至是硬件故障(应该想到过热和其他电源管理相关问题)。



当一个新的,不兼容的内核版本发布时,它可能是最好坚持使用最新支持的内核了一段时间。 NVIDIA公司通常需要几个星期的时间准备新的专有版本,他们认为适合用于一般用途。 耐心一点。如果绝对必要,那么就可以使用epatch_user命令和NVIDIA驱动的ebuild:这允许用户打补丁的NVIDIA驱动程序以某种方式适应了最新的,不支持的内核版本。请注意,即使是NVIDIA驱动维护者,也不NVIDIA将支持这一情况。硬件保修将最有可能是无效的,Gentoo的维护者不能解决问题,因为它是一个专有的驱动程序,只有NVIDIA官方能够正确调试,内核维护者(包括Gentoo和上游)肯定不会支持专有的驱动程序,或任何“污点“系统,当碰巧遇到麻烦时。

如果 genkernel all 是用于配置内核,那么一切都准备好了。如果不是,仔细检查内核配置,启用以下支持:

KERNEL 开启可加载模块支持
[*] Enable loadable module support --->

在内核中也开启“Memory Type Range Register(内存类型范围寄存器)”:

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

With at least some if not all driver versions it may also be required to enable VGA Arbitration and the IPMI message handler:

KERNEL Enable VGA Arbitration
Device Drivers --->
   Graphics support --->
      [*] VGA Arbitration
KERNEL Enable IPMI message handler
Device Drivers --->
   Character devices --->
      [*] IPMI top-level message handler

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) --->
在amd64平台上,IOMMU 控制agpgart的设置。
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

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.

KERNEL Enable simple framebuffer
Bus options (PCI etc.)  --->
   [*] Mark VGA/VBE/EFI FB as generic system framebuffer
Device Drivers --->
   Graphics support --->
        Frame buffer Devices --->
            [*] Simple framebuffer support

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 kernel that the symbolic link points to.

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 tools USE flag. This will install 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/modules-load.d/video.conf and add nvidia to it.

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


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

If secure boot kernel signing is used, then the NVIDIA kernel modules need to be signed before they can be loaded.

This can be accomplished by using the kernel-provided perl script as follows.

root #/usr/src/linux/scripts/sign-file sha512 /usr/src/linux/certs/signing_key.priv /usr/src/linux/certs/signing_key.x509 /lib/modules/Kernel-Version-modules-path/video/nvidia-uvm.ko
root #/usr/src/linux/scripts/sign-file sha512 /usr/src/linux/certs/signing_key.priv /usr/src/linux/certs/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 #/usr/src/linux/scripts/sign-file sha512 /usr/src/linux/certs/signing_key.priv /usr/src/linux/certs/signing_key.x509 /lib/modules/Kernel-Version-modules-path/video/nvidia-modeset.ko

Once the modules are signed, the driver will load as expected on boot up. This module signing method can be used to sign other modules too - not only the nvidia-drivers. Just modify the path and corresponding module accordingly.

X 服务

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


The user(s) needing to access the video card will need to be added to the video group:

root #gpasswd -a larry video

Note that users will be able to run X without permission to the DRI subsystem, but acceleration will be disabled.


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.

使用 NVidia 设置工具

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 part of x11-drivers/nvidia-drivers with the tools USE flag set.

开启 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.



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

要监视 FPS值,运行 glxgears


Blinking console cursor and compat use flag

If a blinking console appears instead of X when using the compat nvidia-drivers USE flag on nvidia-drivers-430 and newer there might have a segmentation fault when xorg starts.

Looking for the segfault:

  1. Boot to the blinking prompt screen
  2. Switch to a tty Ctrl + Alt + F4
  3. Close gdm.
    For OpenRC:
    root #/etc/init.d/xdm stop
    For systemd:
    root #systemctl gdm stop
  4. Launch X to see the output:
    user $ startx

If a segmentation fault error occurs on the nvidia module during startx, rebuild nvidia-drivers without the compat useflag.

FILE /etc/portage/package.use/nvidiaDisabling compat useflag
x11-drivers/nvidia-drivers -compat
root #emerge --ask x11-drivers/nvidia-drivers

Follow bug #684324 for further details.

FATAL: modpost: GPL-incompatible module *.ko uses GPL-only symbol

When the ebuild is complaining about the 'mutex_destroy' GPL-only symbol:

root #emerge x11-drivers/nvidia-drivers
FATAL: modpost: GPL-incompatible module nvidia.ko uses GPL-only symbol 'mutex_destroy' 

Be sure to disable CONFIG_DEBUG_MUTEXES in the kernel's .config file, as suggested by this forum thread.


Linux的NVIDIA驱动程序使用消息信号中断(MSI)在默认情况下。这提供了兼容性和可扩展性优势,主要是由于避免IRQ共享。有些系统存在微星的支持问题,工作时virtual wire经常中断。这些问题表现为NVIDIA驱动程序无法启动X,或CUDA初始化失败。

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/).


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=0660 NVreg_DeviceFileUID=0 NVreg_DeviceFileGID=27 NVreg_ModifyDeviceFiles=1 NVreg_EnableMSI=0


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.

Alternatively, it might be necessary to enable MTRR cleanup support (CONFIG_MTRR_SANITIZER=Y) in the Linux kernel:

KERNEL Enable MTRR cleanup support
Processor type and features  --->
   [*]   MTRR (Memory Type Range Register) support
   [*]   MTRR cleanup support 
   (0)     MTRR cleanup enable value (0-1) 
   (1)     MTRR cleanup spare reg num (0-7)

Failed to initialize DMA on Ryzen

Disable AMD Secure Memory Encryption https://devtalk.nvidia.com/default/topic/1039297/linux/unable-to-start-x-failed-to-initialize-dma-/

KERNEL Disable AMD Secure Memory Encryption (SME) support
Processor type and features  --->
   [ ]   AMD Secure Memory Encryption (SME) support

当试图加载内核模块出现"no such device"


  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" or "efifb" is bound to the graphics card. If so, disable or blacklist this driver.

Xorg 说它找不到任何显示器

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



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
 . . .
0a:00.0 VGA compatible controller: make and model of videocard
 . . . 

Take the first bit, 0a.00.0, translate it to decimal 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:10:0:0"


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.


最近似乎有一些重大的在播放某些类型的NVIDIA二进制驱动的视频,引起慢速视频播放或显著卡顿。这个问题似乎在英特尔 CPU 空闲更换为某些 CPU 而不是常见的 ACPI CPU 减速规造成的。

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.)

If you're using GRUB2 as your bootloader, you can add this kernel parameter to /etc/default/grub like so:

FILE /etc/default/grubAdding intel_idle.max_cstate kernel parameter in GRUB2

Don't forget to run grub-mkconfig -o /boot/grub/grub.cfg after making the change, so that the new configuration is generated (see the GRUB2 page for further details).

After you have rebooted, you can verify that the change is active:

user $cat /sys/module/intel_idle/parameters/max_cstate

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 "Screen"
     . . .
    Option         "metamodes" "nvidia-auto-select +0+0 { ForceFullCompositionPipeline = On }"
     . . .



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


The nvidia kernel module accepts a number of parameters (options) which can be used to tweak the behavior 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.

Pay close attention to this section as these kernel options can enable features that the hardware may or may not support. These options are not forgiving, so be careful with the parameters. Do not made any changes without validating and double-checking that the change is needed.
Attribute Default Description
NVreg_DeviceFileUID 0 Modify the user ID for the device file. The default value sets it to the root user. Setting this to another user ID will make the driver module create the device file with access available to that user ID.
NVreg_DeviceFileGID 27 Modify the Group ID for the device file. The default value sets it to the video group.
NVreg_DeviceFileMode Undefined Set the permissions for the device file. A value of 0660 grants the owner and group-owner read-write access while other users cannot access the device file.
NVreg_ModifyDeviceFiles 1 Instruct the driver to enable or disable dynamic device file management.
NVreg_EnablePCIeGen3 0 Enable PCIe Gen 3.x support. If the system supports this 8GT high speed bus then enable it with this module option flag. When this is enabled but the system does not support Gen 3.0, the behavior of the system can become irratic and unstable. 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 0 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 - a newer way of allocating memory, replacing the older Memory Type Range Register (MTRR) method. The PAT method creates a partition type table at a specific address mapped inside the register and utilizes the memory architecture and instruction set more efficiently and faster. If the computer supports PAT and the feature is enabled in the kernel then this flag can be enabled. Without PAT support, users may experience unstable performance and even crashes if this is enabled. So be careful with these options.
NVreg_EnableVia4x 0 Enable AGP 4x mode in the the NVIDIA driver on Via-chipset-powered systems. Some of these hardware configurations would not work properly in AGP 4x mode when others would. The default leaves it at AGP 2x mode.
NVreg_EnableALiAGP 0 On ALi1541 and ALi1647 chipsets, AGP support is by default disabled by the NVIDIA drivers. The value specifies the speed factor to use, so the values 1, 2, 4 and 8 represent AGP 1x, 2x, 4x and 8x respectively. NVIDIA does not recommend changing the value as it may lead to unstable systems.
NVreg_ReqAGPRate Unspecified Forces the AGP mode on the driver. For instance, a value of 1 means AGP 1x, while a value of 4 means AGP 4x.
NVreg_NvAGP Changes the AGP Gart mode setting. Possible values are: 0 (Disable), 1 (Enable using NVIDIAs internal AGP-Gart), 2 (Enable using the Linux kernel AGP-Gart) and 3 (Enable and use any available, but try th NVIDIA internal one first).
NVreg_EnableAGPSBA 0 Disables (0) or enables (1) AGP Side Banding. For stability reasons, the setting is by default disabled, but the setting can be enabled for testing and debugging purposes. This is not supported by NVIDIA though.
NVreg_EnableAGPFW 0 Enables AGP Fast-Writes when set to 1. Depending on the system's chipset this may cause stability issues if enabled.
NVreg_Mobile 0 Through this setting, users can force the EDID information for particular systems. This workaround is provided for mobile GPU's where EDID information is either non-functional or disabled. Potential values are 0 (Auto detection of the correct setting), 1 (Dell notebooks), 2 (non-Compaq Toshiba laptops), 3 (All other notebooks/laptops), 4 (Compaq Toshiba laptops) or 5 (Gateway machines).
NVreg_RemapLimit 60 Maximum amount of system memory remapping. It specifies the amount of memory that the driver will be allowed to remap through the IOMMU/SWIOTLB on a 64-bit system. Only use it if the IOMMU or SMIOTLB is larger than 64mb. NVIDIA recommends to subtract 4mb from the total amount of memory to use. For instance, the default value is 60 which is in fact 64mb. To set it to 128mb, set the value to 124.
NVreg_UpdateMemoryTypes 0 Tweak the use of page table attributes. Possible values are: 0 (Nvidias logic mechanism), 1 (Enable the use of changed page table attributes) and 2 (Disable the use of page table attributes).
NVreg_InitializeSystemMemoryAllocations 1 Tell the NVIDIA driver to clear system memory allocations prior to using it for the GPUs. Disabling can give a slight performance boost but at the cost of increased security risks. By default the driver will wipe the allocated by zeroing out its content.
NVreg_UseVBios 1 Enable or disable the use of the video BIOS int10 code. Set to 0 to disable.
NVreg_RMEdgeIntrCheck Unspecified Enable or disable checking for edge-triggered interrupts.
NVreg_EnableMSI 0 Enable or disable PCIe-MSI capabilities. Enable this to use MSI interrupts instead of wired interrupts.
NVreg_MapRegistersEarly 0 If set to 1, allow 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.
NVreg_RegisterForACPIEvents 1 Enable the driver to register with the ACPI of the system to receive ACPI events. This can be disabled (0) when issues occur with ACPI or while debugging an issue.

编辑/etc/modprobe.d/nvidia.conf 文件, 然后更新模块信息:

root #update-modules

Unload the nvidia module...

root #modprobe -r nvidia


root #modprobe nvidia

高级 X 配置

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


This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Sven Vermeulen (SwifT), , M Curtis Napier and Chris Gianelloni
They are listed here because 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 each article's associated history page.