Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



First off, why this guide when there is already an official one? The answer is that the official one leaves out some stuff, and well, the wiki is really where this should all be.


Before continuing with the article, it is important to provide you with some information.

Legacy vs. Current

The drivers for older "legacy" graphics cards used to be held in a seperate package called nvidia-legacy-drivers. This is no longer the case and all drivers are now in the nvidia-drivers package. See "Installing the drivers" further down for selecting the correct driver.

XOrg Drivers vs. nVidia Drivers

There are several different groups developing drivers that support nVidia graphics cards on Linux. The XOrg team has an open source driver called 'nv' that you can install as part of xorg-x11. The driver that is the focus of this article is the proprietary driver released by the fine folks at nVidia, called 'nvidia'. Only a small amount of code is given to be able to interface the kernel and the actual nvidia driver. These two projects have nothing to do with each other, and keeping them straight is important, especially when you start configuring XOrg near the end of this article. You only need one or the other--not both--and this article will help you install the one released by nVidia.

Preparing Your System

The official nVidia drivers are provided in 2 parts - the kernel module and the Xorg driver, both of which are held in the nvidia-drivers package. You therefore, need to make sure your kernel is set up to support module loading. The kernel module also requires access to MTRRs (Memory Type Range Registers) so these need to be enabled in your kernel.

Selecting the Right Kernel

Kernel module packages use the /usr/src/linux symlink to determine which kernel they should build against. If this link is already correct, move on to Required Kernel Settings.

Usually kernel modules should be built against the currently running kernel, so find out what that is by running: uname -a

Gentoo provides a handy tool for changing lots of settings on the system called eselect. One of eselect's modules is for changing the /usr/src/linux symlink.

Note: You can find out more about eselect and the settings it can change by running: eselect help

List all available kernel source directories with: eselect kernel list

Find out which one the symlink is currently pointing to with: eselect kernel show

Now set the kernel source directory to point the /usr/src/linux symlink to with eselect kernel set <n> where <n> is the number next to the kernel you wish to set the symlink to point to. For example, if the symlink should point to the number 5 item in the list, run: eselect kernel set 5

Required Kernel Settings

Note: If you built your kernel with genkernel, you should be able to skip this section.

Make sure you have the following options enabled:

Linux Kernel Configuration: Kernel Configuration
General setup --->
 [*] System V IPC
Loadable Module Support --->
 [*] Enable Loadable Module Support
Processor Type and Features --->
 [*] MTRR (Memory Type Range Register) Support

AGP support is optional, dependent on your type of graphics card:

Linux Kernel Configuration: Kernel Configuration
Device Drivers --->
 Character devices --->
 (in kernel 2.6.24 it is:
 Graphics support --->)
  [*] /dev/agpgart (AGP Support)

Make sure you have the following options disabled. These options conflict with nVidia's driver:

Linux Kernel Configuration: .config
Device Drivers --->
 Graphics Support --->
   (in kernel 2.6.24 it is:
   Support for frame buffer devices --->)
  < >   nVidia Framebuffer Support
  < >   nVidia Riva support

If you need help configuring, building, and installing your new kernel, read the official Gentoo kernel guide.

Selecting the nVidia Driver Version

Note: Upgrading From nvidia-kernel and nvidia-glx Packages

The new style combined package nvidia-drivers conflicts with the old split packages of nvidia-kernel and nvidia-glx, so these must be removed first. If you're not sure whether or not you have the old style packages installed, unmerge the old split driver packages with using the following command:

% emerge --unmerge nvidia-kernel nvidia-glx
If the above command tells you that that the packages couldn't be found, then they weren't installed. The message can be safely ignored.

Determining Your Card ID and Model

Use lspci to find out what card you have. Note the identifier of the target card you wish to enable support for. (Adding -v or -vv will increase verbosity.)

# lspci
00:00.0 Host bridge: Intel Corporation 82845G/GL[Brookdale-G]/GE/PE DRAM  Controller/Host-Hub Interface (rev 01)
00:01.0 PCI bridge: Intel Corporation 82845G/GL[Brookdale-G]/GE/PE Host-to-AGP Bridge (rev 01)
00:1d.0 USB Controller: Intel Corporation 82801DB/DBL/DBM (ICH4/ICH4-L/ICH4-M) USB UHCI Controller #1 (rev 01)
00:1d.1 USB Controller: Intel Corporation 82801DB/DBL/DBM (ICH4/ICH4-L/ICH4-M) USB UHCI Controller #2 (rev 01)
00:1d.2 USB Controller: Intel Corporation 82801DB/DBL/DBM (ICH4/ICH4-L/ICH4-M) USB UHCI Controller #3 (rev 01)
00:1d.7 USB Controller: Intel Corporation 82801DB/DBM (ICH4/ICH4-M) USB2 EHCI Controller (rev 01)
00:1e.0 PCI bridge: Intel Corporation 82801 PCI Bridge (rev 81)
00:1f.0 ISA bridge: Intel Corporation 82801DB/DBL (ICH4/ICH4-L) LPC Interface Bridge (rev 01)
00:1f.1 IDE interface: Intel Corporation 82801DB (ICH4) IDE Controller (rev 01)
00:1f.5 Multimedia audio controller: Intel Corporation 82801DB/DBL/DBM (ICH4/ICH4-L/ICH4-M) AC'97 Audio Controller (rev 01)
01:00.0 VGA compatible controller: nVidia Corporation NV17GL [Quadro4 200/400 NVS] (rev a3)
05:08.0 Ethernet controller: Intel Corporation 82801DB PRO/100 VM (LOM) Ethernet Controller (rev 81)

Using the -ns option followed by the identifier will allow you to see the actual ID # as it should appear on the List of Supported Devices.

# lspci -ns 01:00.0
01:00.0 0300: 10de:017a (rev a3)
                   actual Device PCI ID - search for this on the list

Installing the drivers

To install the driver, you need to install x11-drivers/nvidia-drivers.

The nvidia-drivers package supports the full range of available nVidia cards. Multiple versions are available for installation, depending on the card(s) you have.

You can check for driver compatibility for your card at to determine which driver supports it at the nVidia's Legacy GPU page or Supported NVIDIA GPU Products (169.12).

Warning: Don't forget to run dispatch-conf or etc-update to update your configuration files if you are told to do so.

Installing the Latest "Unstable" Release

If you want to run the latest "testing" release, i.e. the latest release from nVidia, you will need to unmask and install the newest x11-drivers/nvidia-drivers package. You should first unmask x11-drivers/nvidia-drivers package by adding the following line to your /etc/portage/package.keywords file:

File: /etc/portage/package.keywords

This can be accomplished by running

Code: Command
# echo "x11-drivers/nvidia-drivers ~x86" >> /etc/portage/package.keywords

Beta Drivers

On some occasions, the very latest nVidia drivers will be masked by package.mask. This usually happens when those drivers are considered "beta" by nVidia - ie. even nVidia considers them unstable. To use these drivers, you'll need to add the following line to both your /etc/portage/package.unmask and /etc/portage/package.keywords files:

File: /etc/portage/package.unmask & package.keywords

Configuring XOrg/X11

Configuring XOrg is relatively easy. The xorg.conf file is pretty straight forward, you just have to get used to the syntax.

Switching to the New Driver

The xorg configuration file needs to be updated so that X will use the new driver. To do this, edit your xorg.conf file, locate the Device section that refers to your graphics card and change the Driver line to nvidia.

To open the xorg.conf file for editing, run nano -w /etc/X11/xorg.conf

Find the 'Device' section where the graphics card is configured and replace the Driver entry with 'nvidia'. The following shows an example "before and after".

File: xorg.conf: Change Driver to 'nvidia'


 Section "Device"
  Identifier "GeForce2 Pro/GTS"
  Driver     "nv"
  VideoRam   65536


 Section "Device"
  Identifier "GeForce2 Pro/GTS"
  Driver     "nvidia"
  VideoRam   65536

Activating GLX

To enable 3D acceleration, the GLX module needs to be activated and both the DRI and GLcore modules must be deactivated.

In the xorg.conf file:

File: xorg.conf: Settings required for nvidia 3D acceleration
Section "Module"
Load "glx"
# Load "dri"
# Load "GLcore"

Now, the module is enabled in configuration, but in order for it to work X must be running in either 16 or 24-bit color mode.

To do this set the DefaultDepth setting in the 'Screen' section of the xorg.conf as shown in the example below. Please note that there must be 16-bit and/or 24-bit modes in the "Display" subsection of the "Screen" section.

File: xorg.conf: Setting the Default Color Depth
 Section "Screen"
  DefaultDepth 24
  SubSection "Display"

There are a number of different opengl libraries available and it's possible to install more than one. To manage this situation, Gentoo uses the eselect tool (as already shown earlier).

Note: To find out more about the eselect tool and its options, run: eselect help

To tell Gentoo to use the nvidia opengl implementation, run: eselect opengl set nvidia

Wrap It Up

Adding Users to the Video Group

To protect the system from malicious activities, linux restricts the users that can access a given piece of hardware. In the case of the video card (which needs to be accessed for 3D acceleration), users must be members of the 'video' group.

For each user you wish to allow to use 3D acceleration, run: gpasswd -a <username> video where <username> is the name of the user you wish to add to the group.

(Re)starting X

Now X must be restarted with the new configuration. You'll want to read all of this section before carrying out any commands.

If you are logged in to X, first log out (usually by choosing "Log Out" or "quit" from the menu of your desktop environment.

If you're at the console, restart X with: startx

If you're at a graphical login screen, you still need to restart X. This can be achieved by pressing Ctrl + Alt + Backspace. This key combination kills the currently running X server. X is then restarted by the desktop manager (xdm, gdm or kdm).

Testing Your Configuration

To ensure that 3D acceleration is working, from a console running inside of X and as a normal user (not as root), run: glxinfo | grep direct

You should see that direct rendering is enabled, as shown in the example output below.(If you get the message: "bash: glxinfo: command not found" do "emerge x11-apps/mesa-progs")

Code: Command output example
direct rendering: Yes
Note: Another tool for testing GLX is 'glxgears', however this doesn't show whether direct rendering is actually enabled and can't be used as a benchmark.

Extra Configuration Options

Remove the nvidia splash screen

Normally when X starts with the nvidia drivers installed, a splash screen is shown. This can be removed by setting the NoLogo option to "true" as shown in the example below.

File: xorg.conf: Disable nvidia splash screen
 Section "Device"
  Identifier "GeForce2 Pro/GTS"
  Driver     "nvidia"
  VideoRam   65536
  Option     "NoLogo" "true"

Activating NV30 Emulation for lower architectures

Unless you know what this does, you should not use it. It will not increase performance. It is possible (even if no longer advertised on nvidia page) to emulate NV30 architecture on older cards. For example, you can run FX pixel shaders on an NVIDIA GeForce 2 Go. The point is to add option "NVEmulate" to the /etc/X11/xorg.conf file, section that concerns nvidia:

Code: Enabling emulation of NV30 NVIDIA architecture
 Section "Device"

  Option "NVEmulate"  "30"  
  Driver "nvidia"

Maybe it is possible to use the value "40" instead of "30" in order to see if there is some difference... maybe it means that also NV40 architecture can be emulated. KEYWORDS for search engines (since it is difficult to find this info): __GL_NV30EMULATE , GL_NV30_EMULATE

Activating Coolbits; Overclocking Controls for nVIDIA Settings

Proceed with caution! There is a minor chance of damaging your GPU through over-clocking.

There are many fine pages about where to begin with overclocking, you should read several and fully understand what you are doing before altering the settings for your card.

Beginning with version 1.0-7664, Coolbits, support for GPU clock manipulation, is included.

To activate Coolbits, open xorg.conf in a text editor and add the following line in Section "Device" :

File: xorg.conf: Enabling Coolbits
Option   "Coolbits" "1"

Restart your X-server and nvidia-settings.

There will be a new item in the left column list of categories in nvidia settings; Clock Frequencies. Click on the "Enable Overclocking" checkbox and read and accept the license agreeement.

You can now set the frequencies yourself or use the auto detect feature to find "optimal" values. The overclock settings will not survive restarting X.

To fix this, add this line to your .xinitrc

File: .xinitrc:
nvidia-settings --assign "[gpu:0]/GPUOverclockingState=1" --assign "[gpu:0]/GPU2DClockFreqs=<gpu clock>,<mem clock>" --assign="[gpu:0]/GPU3DClockFreqs=<gpu clock>,<mem clock>" &

The first set of tags (GPU2DClockFreqs) is for 2D and the second set of tags (GPU3DClockFreqs) is for 3D. Substitute <gpu clock> and <mem clock> with your desired GPU and memory clock frequencies, respectively. If you have a second graphic card in your system, add another line and change [gpu:0] to [gpu:1].


Black/Blank screen when starting X

Symptoms: A black/blank screen when X starts, followed by the monitor going in standby mode after a moment. Ctrl+Alt+Backspace doesn't kill X and get you back to the console. Problem: This issue is caused by bad refresh rate values given to X in your xorg.conf config file.

In order to fix this, you will need to find the correct HorizSync and VertRefresh values for your monitor. Here's a list of values that did NOT work for me:

In fact what saved my life was to install ubuntu on my second hard drive, and to use the values for HorizSync and VertRefresh that were generated by the Ubuntu installer in the /etc/X11/xorg.conf config file. Instead of installing a whole Ubuntu system like I did, I suggest you boot on a LiveCD, it might just work as well. If you are very unlucky and you still haven't found the good refresh rate for your monitor + the nvidia drivers, i suggest you try mine, in case it works:

Code: Example Monitor Configuration
Section "Monitor"
	Identifier   "Monitor0"
	HorizSync    28-64
	VertRefresh  43-60

You can also attempt searching online for others' configurations for your monitor. It worked for me. ~Terrestrial Host

If it still does not work, then I wish you good luck at trying to guess the good refresh rate for your monitor.

I ran nvidia-xconfig and it generated the proper settings. startx worked the first time.

Unable to validate video modes

If, as I do, you have an older monitor with bad or no DDC/EDID information, nvidia-auto-select may fail to validate your perfectly good modelines that have worked for years, leaving you stranded with 1024x768, or worse. To fix this, add Metamodes to your monitor section like this:

Section "Monitor"
     Option "Metamodes" "1600x1200"

This apparently tricks the nvidia driver into actually trying to find a good mode for your monitor, rather than just giving you a bad default. I don't know why this is true, but this fix worked for me.

Error: cannot handle TLS data

After re-emerging several times the nvidia drivers, it may happen that the glx module fails to load without any apparent reason, with the error " cannot handle TLS data". This issue is caused by two files being inverted, /usr/lib/opengl/nvidia/tls/ and /usr/lib/opengl/nvidia/no-tls/ The fix is quite simple: swap the two files. Before trying this, check to see if the file in the no-tls folder is smaller than the one in the tls folder. If it is the case, then the files are already in the correct folder, so do not swap them. If it is not the case, then you can swap them with this command:

Code: Command to swap inverted files
mv /usr/lib/opengl/nvidia/tls/ /usr/lib/opengl/nvidia/tls/ && mv /usr/lib/opengl/nvidia/no-tls/ /usr/lib/opengl/nvidia/tls/ && mv /usr/lib/opengl/nvidia/tls/ /usr/lib/opengl/nvidia/no-tls/

Restart X and the glx module should load fine, this time. If not, update your glibc!

UDev Users: Fix Device Creation Problem

UDev doesn't like nVidia... or maybe nVidia doesn't like UDev. Either way, you have to run '' to build the character devices that allow your computer to access your card. Here's the rub. You'll probably have to run every time you boot up your computer. Which isn't difficult. Just do the following:

Code: Build nVidia Devices on Boot
 #echo '' >> /etc/conf.d/local.start

Ok, problem solved. Your local.start script will run during boot, before the computer switches to your default runlevel so you're safe to have your computer boot into GDM or whatever graphical login manager you choose... Well, relatively safe - See: TIP Fix The Login Security Hole

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

Copied From Guide

If you are having troubles with the nVidia 2D acceleration it is likely that you are unable to set up a write-combining range with MTRR. To verify, check the contents of /proc/mtrr:

Code: Checking if you have write-combining enabled
 # cat /proc/mtrr

Every line should contain "write-back" or "write-combining". If you see a line with "uncachable" in it you will need 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. You will now find out that there is no "uncachable" entry anymore and 2D acceleration now works without any glitches.

I receive warnings about unsupported 4K stack sizes

Copied From Guide

nvidia-kernel packages older than 1.0.6106 only support kernels using an 8K stack size. More recent kernels (2.6.6 and higher) have support for 4K stack size's as well. Do not select 4K stack size in your kernel configuration if you are using such an nvidia-kernel package. You can find this option in the section Kernel Hacking.

When I attempt to load the kernel module I receive a "no such device"

Copied From Guide

This usually occurs when you don't have a matching video card. Make sure that you have an nVidia-powered graphical card (you can double-check this using lspci).

If you are confident that you have an nVidia card, check your BIOS and see if the directive Assign IRQ to VGA is set.

You also get this error if you have compiled in the nvidia framebuffer driver in your kernel. Use vesafb instead.

This error also occurs if you compiled your kernel with a custom version string (a la menuconfig --> General Setup). The install process does not like spaces, or leading dashes (minus signs, hyphens ...). The install process will truncate the name at the first space, and dump the modules into that directory (do ls /lib/modules/* to check for this). It finds the modules just fine, but can't hook into the kernel.

dmesg or building the module returns unknown symbol errors

dmesg output gives something like this:

nvidia: module license 'NVIDIA' taints kernel.
nvidia: Unknown symbol remap_page_range
nvidia: Unknown symbol pci_find_class
nvidia: Unknown symbol remap_page_range
nvidia: Unknown symbol pci_find_class
nvidia: Unknown symbol remap_page_range

Possible solutions:

Most likely the fault is ccache Forum thread Bug report. Disable it when rebuilding this module by issuing the command
FEATURES="-ccache" emerge nvidia-drivers
Edit your kernel menuconfig and check:
--> Device drivers
    --> Character devices  
        [*] SiS chipset support
        [*] SiS video cards
This might help because pci_find_class is in the drivers/video/sis/sis.h file.

When I attempt to load the kernel module I receive a "insmod: error inserting ... Invalid module format"

This type of error can be diagnosed by running:

The output from this command will indicate the source of the problem. In my case at least it was due a kernel misconfiguration
should be "<arch><kernel> preempt <gcc version>"

If the kernel is not compiled to be a preemptible kernel then trying to insert the nvidia.ko module will fail. To make the kernel preemptible use your favorite text editor to modify your kernel's configuration file (defaultly .config) and be sure to ammend:

Code: Adding or modifying the CONFIG_PREEMPT setting

As well as commenting out all other CONFIG_PREEMPT type options.

Recompile, and installing the nvidia module should work successfully. --Pderry 18:45, 15 March 2006 (GMT)

EDIT : in my case, the nvidia module said that it was compiled with a different version of gcc than the kernel itself. Recompiling the kernel with the same version of gcc solved the problem.

X freezes when running glxinfo or OpenGL apps

It may happen that freezes everytime you launch an OpenGL app, even glxinfo does the job. This is caused by the nvidia driver oopsing in the background, which you can watch by tail-ing /var/log/messages over ssh. One reason for this is the nvidia drivers not liking a kernel with PaX (hardened-sources) or an enabled NX/XD-Bit (NoeXecute/eXecuteDisable) in your BIOS. If you have no special reason to have this enabled, disable it and nvidia will magically work - at the loss of some security. Otherwise there are several patches floating around the forums.

Whole system freezes on Logout or Switching to Console

A workaround for this problem is to disable the framebuffer console, by Compiling a Kernel without vesafb-tng, or (if you use standard vesafb) by not using "vga=" kernel parameters in your bootloader. [1]

Note: This workaround did not help me and many others (see later forum posts). I had to revert to the 1.0.9639 driver. The problem seems to exist for some people (especially with Sony laptops) even with the latest driver (nvidia-drivers-100.14.23).

50hz refresh rate

If the refresh rate is shown as 50hz, then disable DynamicTwinView in /etc/X11/xorg.conf in the Device or Screen sections. This option is also described in /usr/share/doc/nvidia-drivers-*/README.bz2

Section "Device" or Section "Screen"
Option "DynamicTwinView" "False"

I just upgraded to nvidia-drivers-173.14.09 and now everything looks horrible

If your display looks washed out, with ringing and high contrast then it is likely your monitor is reporting that it is a TV. nVidia's newest drivers now read EDID extensions. You need to provide fake EDID information to the driver. More information here: Fixing Ugly DVI/HDMI Displays due to EDID bugs on nVidia drivers


* You must be in the video group to use the NVIDIA device
* For more info, read the docs at
* This ebuild installs a kernel module and X driver. Both must
* match explicitly in their version. This means, if you restart
* X, you most modprobe -r nvidia before starting it back up
* To use the NVIDIA GLX, run "eselect opengl set nvidia"
* nVidia has requested that any bug reports submitted have the
* output of /usr/bin/ included.
* To work with compiz, you must enable the AddARGBGLXVisuals option.
* If you are having resolution problems, try disabling DynamicTwinView.
* GNU info directory index is up-to-date.

Related Articles

Retrieved from ""

Last modified: Sun, 28 Sep 2008 05:20:00 +0000 Hits: 120,202