Differences between revisions 1 and 10 (spanning 9 versions)
Revision 1 as of 2005-11-14 06:49:41
Size: 5161
Comment: just starting
Revision 10 as of 2005-12-23 05:25:41
Size: 29087
Comment: /dev/nvidia*
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
This document explains how to make use of NVIDIA video hardware for ["Debian"] GNU/Linux users, who are the primary target. However, most (if not all) of Debian derivatives, including Libranet, Mepis, Ubuntu, and Xandros, should work in the same way. The following section shortly describes the ["free"] drivers while the rest of the document covers the non-free but 3D-accelerated drivers. This document explains how to make use of NVIDIA video hardware for ["Debian"] GNU/Linux users, who are the primary target. However, most (if not all) of Debian derivatives, including Libranet, Mepis, Ubuntu, and Xandros, should work in the same way. The following section shortly describes the ["free"] drivers while the rest of the document covers the ["non-free"] but 3D-accelerated drivers.

[[TableOfContents]]
Line 7: Line 9:
However, both of these drivers do not support 3D acceleration. Only the ["non-free"] '''nvidia''' driver supports this. If you are willing to use this driver despite the fact that it is non-free, read the following section. If you do, keep in mind that using the non-free drivers is considerably more complex and things are much more likely to break. If this happens and you give up trying to get X working again due to the '''nvidia''' driver, remember that simply switching back to one of the free drivers should let you run X again until you find a way to get 3D acceleration working again. However, both of these drivers do not support 3D acceleration. Only the non-free '''nvidia''' driver supports this. If you are willing to use this driver despite the fact that it is non-free, read the following section. If you do, keep in mind that using the non-free drivers is considerably more complex and things are much more likely to break. If this happens and you give up trying to get X working again due to the '''nvidia''' driver, remember that simply switching back to one of the free drivers should let you run X again until you find a way to get 3D acceleration working again.
Line 20: Line 22:
    * It's more automated once it's set up, so it saves you work if you rebuild your kernel very often, as I do.
    * It uses the Debian package management tools, so it's cleaner.
    * If you're already using make-kpkg to build your kernel, it fits easily into your existing build procedure.
    * It will also save you work if you build other kernel modules (e.g. lm-sensors or fuse) outside of the kernel tree, because all of the driver packages get built at the same time with a single invocation of make-kpkg.
    * module-assistant has now taken much of the grunt work out of this task, making it about as easy as using the official installer.

However, you don't have to build your drivers this way. Many people prefer just to get and run an official installer from nVidia. This method also has advantages:

    * You may get more recent versions of the NVIDIA drivers, since the Debian packages tend to lag by a month or two, which can be needed if the version in Debian didn't support your hardware. You can compare the [http://www.nvidia.com/object/unix.html current version] and the [http://packages.debian.org/nvidia-glx version in your Debian release] to see how much difference there is.
    * The official installer is easy to use, although you will probably get tired of rerunning it if you rebuild your kernel more than a few times. (Every time you rebuild your kernel you have to wait until you reboot, wait for your X server to die, navigate the installer menus, and then restart X. It gets old. That's why this guide was writen :)
    * You won't have to learn about module-assistant, or make-kpkg. Wait, is this an advantage?
    * People have occasionally reported that even after some work, they just couldn't get their drivers to work using the Debian way. Once they used the NVIDIA installer everything worked smoothly.
 * It's more automated, so it saves you work if you change your kernel.
 * It uses the Debian package management tools, so it's cleaner.
 * It can be done while X is running. You only have to restart X at the end, when you want the driver change to be applied.
 * If you're already using make-kpkg to build your kernel, it fits easily into your existing build procedure.
 * It will also save you work if you build other kernel modules (e.g. lm-sensors or fuse) outside of the kernel tree, because all of the driver packages get built at the same time with a single invocation of make-kpkg.
 * You won't need to download NVIDIA's official installer from nvidia.com. The Debian packages contain all of the parts of it that you need.

However, you don't have to build your drivers this way. Many people prefer just to get and run NVIDIA's official installer. This method also has advantages:

 * You may get more recent versions of the NVIDIA drivers, since the Debian packages tend to lag by a month or two, which can be needed if the version in Debian didn't support your hardware. You can compare the [http://www.nvidia.com/object/unix.html current version] and the [http://packages.debian.org/nvidia-glx version in your Debian release] to see how much difference there is.
 * The official installer is easy to use, although you will probably get tired of rerunning it if you rebuild your kernel more than a few times. (Every time you rebuild your kernel you have to wait until you reboot, wait for your X server to die, navigate the installer menus, and then start X. It gets old. That's why this guide was written :) ) Note: the Debian way is similarly easy.
 * You won't have to learn about module-assistant...wait, is this an advantage?
 * People have occasionally reported that even after some work, they just couldn't get their drivers to work using the Debian way. Once they used the NVIDIA installer everything worked smoothly.
Line 37: Line 40:
Here are the instructions for building and installing NVIDIA 3D drivers, the Debian way.
=== Overview ===
The NVIDIA driver consists of two parts: a kernel module, and a collection of user-space libraries. The libraries (sometimes called the "binary driver" or GLX libraries) are distributed in binary form by NVIDIA, and packaged for Debian in the nvidia-glx package. The kernel module (aka the "kernel interface to the binary driver") is distributed in source form (though with one binary component), and packaged for Debian in the nvidia-kernel-source and nvidia-kernel-common packages. The version of the kernel module has to match the version of the libraries. The user libraries and kernel module source only have to be installed once. Then the kernel module has to be rebuilt every time you change or rebuild your kernel. So, here's what you have to do:

   1. Build and install the kernel module.
   2. Install the user-space libraries.
   3. Configure X to use the '''nvidia''' driver and add the '''nvidia''' module to /etc/modules

Step 2 has to be performed after step 1 because of some dependencies, as explained below.

Steps 2 and 3 have to be performed only once. Step 1 has to be repeated every time you change your kernel, but with the help of module-assistant, apt-get, and make-kpkg, it's hardly any work at all. We'll come back to this at the end of the installation section.

=== Steps ===
==== Build and install the kernel module ====
===== Stock or Custom Kernel? =====
Some of the installation methods below depend on whether you're running a stock kernel, i.e. a prebuilt kernel from the Debian distribution. If you know which kind of kernel you have, you can skip to the following section.

By default, Debian comes with a stock kernel. If you don't know what kind of kernel you're running, then it's probably a stock kernel. If you're not sure, run
{{{
$ uname -r
}}}
and check if the output looks like 2.*.*-small number-architecture (e.g. 2.4.27-2-386 or 2.6.8-2-k7). If it does, you're most likely running a stock kernel.

===== Methods =====

There are four different methods that you can use to install the kernel module. If that sounds like a lot, don't worry—they're listed in order of difficulty. So start with the first one, and if it doesn't work for you, go on down the list.

====== Use module-assistant ======
This method is very easy, and should work for most people, with either a stock or custom kernel.

Install module-assistant if you don't have it, and nvidia-kernel-common. To do it with apt-get:
{{{
# apt-get install module-assistant nvidia-kernel-common
}}}
Then run:
{{{
# m-a prepare
# m-a auto-install nvidia
}}}
And that's it. If all went well, your '''nvidia''' kernel module is now built and installed; you may proceed to step 2.

Note: you must use the same version of gcc to build your nvidia kernel module as was used to build your kernel. This might be a problem if you are running a stock kernel. If module-assistant fails, read its log output and look for messages suggesting that you need, for example, gcc-3.4 instead of gcc-3.3.

====== Install a pre-built module ======
This method is easy if you're running a recent stock kernel for which a pre-built module is available; it will not work at all if you're running a custom kernel. If the module-assistant method doesn't work for you and there are pre-built modules available for your kernel, use this method.

As of this writing, pre-built modules are only available for kernel 2.4.27, Sarge's default kernel. There are no pre-built modules for 2.6.8. If you don't know your kernel version, run
{{{
$ uname -r
}}}
If there is a pre-built module for your kernel, install its package (the name starts with "nvidia-kernel-". To do it with apt-get:
{{{
# apt-get install nvidia-kernel-$(uname -r)
}}}

If this step succeeds, you may now proceed to step 2. If not, try a different installation method.

====== Build manually, with a stock kernel ======
Use this method if you're running a stock kernel and the two previous methods failed or didn't apply to you. module-assistant should automate this process. In other words, if the first method failed but this one works, you should probably submit a bug report against module-assistant.

The following procedure is adapted from the instructions in /usr/share/doc/nvidia-kernel-source/README.Debian and is known to be potentially inexact.

         1. Save the release number of your kernel (e.g. 2.4.27-2-k7 or 2.6.8-1-686) in a couple of environment variables:

                export KVERS=$(uname -r)
                export KSRC=/usr/src/kernel-headers-$KVERS

            Note that these variables are used by the build commands below, so you really do need to set and export them, as in the above commands.
         2. Install the kernel module source: run

                apt-get install nvidia-kernel-source nvidia-kernel-common

            This will give you a source tarball /usr/src/nvidia-kernel-source.tar.gz. Unpack it with

                cd /usr/src
                tar -zxf nvidia-kernel-source.tar.gz

            This will unpack the kernel module sources into /usr/src/modules/nvidia-kernel.
         3. Install the header files for your kernel:

                apt-get install kernel-headers-$KVERS

            This will give you kernel header files in /usr/src/kernel-headers-$KVERS. Be sure to check that the installed kernel image and kernel header packages have the same version number: run

                apt-cache policy kernel-image-$KVERS kernel-headers-$KVERS

            and check that the version number listed as Installed is the same for both packages. If it isn't, find the distribution that has the version of kernel-headers that you need, e.g. testing, and rerun the above installation command, adding '-t testing' (or whichever).
         4. Build the kernel module package:

                cd /usr/src/modules/nvidia-kernel
                debian/rules binary_modules

            The result will be a package file /usr/src/nvidia-kernel-*.deb, which contains your kernel module.

            Note: several users have told me recently that their nvidia package file ends up in /usr/src/modules, instead of /usr/src. I don't know yet why this happens. If this is your case, please adjust the next command appropriately.
         5. Install the kernel module:

                dpkg -i /usr/src/nvidia-kernel-*.deb

            Use the fileglob as above if you want, but watch out that you don't have more than one nvidia-kernel package file lying around in /usr/src. If you do you'll get a blizzard of error messages. It's probably better to explicitly type all of the version information that I rendered as * above.
      Now proceed to step 2, below.

====== Build manually, with a custom kernel ======
Use this method if you're configuring and building a custom kernel.

1. Install the kernel module source. To do it with apt-get:
{{{
# apt-get install nvidia-kernel-source nvidia-kernel-common
}}}
This will give you a source tarball /usr/src/nvidia-kernel-source.tar.gz. Unpack it with:
{{{
$ cd /usr/src
# tar -zxf nvidia-kernel-source.tar.gz
}}}
This will unpack the kernel module sources into /usr/src/modules/nvidia-kernel.

2. Configure your kernel. This step isn't documented here; if you need to learn how, see the kernel-package documentation. But in summary, what you have to do is
{{{
$ cd /usr/src/linux
# make xconfig
}}}
and then choose the options you want. Note, however, that each of the following kernel options has been reported to cause trouble with the '''nvidia''' driver:
 * Graphics Support –> nVidia Riva support (FB_RIVA)
 * Processor Type and Features –> Local APIC support on uniprocessors (X86_UP_APIC) (not available if you have an SMP kernel, including hyperthreading)
It is therefore recommended that you disable all of the above options in your kernel configuration. If for some reason you don't disable them, and then your X display doesn't work properly with the '''nvidia''' driver, you should suspect these options as the likely cause of the trouble. For more details, see the troubleshooting page.

3. Build the kernel and the nvidia kernel module:
{{{
$ cd /usr/src/linux
# make-kpkg clean
# make-kpkg kernel_image modules_image
}}}
For an introduction to using make-kpkg to build kernel packages, see "Creating custom kernels with Debian's kernel-package system", or "Compiling Kernels the Debian Way". See also the make-kpkg man page, for a description of other options and targets that you can use in this command.

The result of the above command will be two Debian package files, { kernel | linux }-image-*.deb and nvidia-kernel-*.deb, both in /usr/src or /usr/src/modules. The first file contains your kernel, and the second contains your '''nvidia''' kernel module.

At the same time, if you have sources for any other add-on kernel modules in /usr/src/modules, then the "modules_image" target will cause make-kpkg to build Debian package files for them, too. For example, if you install the fuse-source package you'll get a source archive /usr/src/fuse.tar.gz, which you can unpack to get fuse module sources in /usr/src/modules/fuse. If you've done this, then this same invocation of make-kpkg will also build a fuse module package file, /usr/src/fuse-*.deb, that's specific to your new kernel.

4. Install the new kernel and kernel module:
{{{
$ cd /usr/src
# dpkg -i /path/kernel-image-*.deb /path/nvidia-kernel-*.deb
}}}
Use the fileglobs as above if you want, but watch out that you don't have more than one kernel-image or nvidia-kernel package file lying around in /usr/src. If you do you'll get a blizzard of error messages. It's probably better to explicitly type all of the version information rendered as * above.

==== Install the NVIDIA user-space libraries ====
Install the nvidia-glx package. To do it with apt-get:
{{{
# apt-get install nvidia-glx
}}}
Note
 * The reason this step has to come after step 1 is that nvidia-glx depends on a virtual package called 'nvidia-kernel-$NVVERSION', where $NVVERSION is the version number of the nvidia-glx package. This virtual package should be provided by the kernel module package that you installed in step 1; so you have to complete that step first.

==== Update your configuration ====
1. Update your X configuration. There are two ways to do this. The one you should use depends on whether you manually edited your X configuration file. If you don't know if you did, you probably didn't. To make sure, run one of the following commands, depending on your X server. Note that if you run Sarge and choose the debconf way but you did edit your X config file, your changes will be quietly ignored.

For XFree86 (Sarge):
{{{
$ md5sum /etc/X11/XF86Config-4|diff -sq /var/lib/xfree86/XF86Config-4.md5sum -
}}}
For X.org (Etch):
{{{
$ md5sum /etc/X11/xorg.conf|diff -sq /var/lib/xfree86/xorg.conf.md5sum -
}}}
If the files differ, choose the second way (the manual way).

===== The debconf way =====
As a suggestion, save yourself some possible grief later by backing up your current X config file.
For XFree86 (Sarge):
{{{
# cp -p /etc/X11/XF86Config-4 /etc/X11/XF86Config-4.bak
}}}
For X.org (Etch):
{{{
# cp -p /etc/X11/xorg.conf /etc/X11/xorg.conf.bak
}}}

2. Tell Debian that XF86Config-4 has never been edited:

                            md5sum /etc/X11/XF86Config-4 >| /var/lib/xfree86/XF86Config-4.md5sum

                        If you don't perform this step, and you have ever edited XF86Config-4, then dpkg-reconfigure will lead you through its whole questionnaire below, and then silently fail to write a new XF86Config-4. This is Debian bug #223929.
Run the following command.
For XFree86 (Sarge):
{{{
# dpkg-reconfigure xserver-xfree86
}}}
For X.org (Etch):
{{{
# dpkg-reconfigure xserver-xorg
}}}
This will ask you a long series of questions that you should have already seen at least when you installed Debian. You only need to change your answer to 2 of those questions. When asked to choose an X server driver, choose '''nvidia'''. Then, when asked to select X server modules, deselect (uncheck) GLCore and dri, and select (check) glx.

Finally, if you use Sarge, you may want to verify that your X config file was written. To do so, run:
{{{
$ ls -l /etc/X11/XF86Config-4
}}}
and check that the date printed is current.

===== The manual way =====
This method will preserve any customizations you've made to XF86Config-4. Just watch out for typos, and check /var/log/XFree86.0.log if you've recently edited XF86Config-4 and things go wrong.

                  Edit /etc/X11/XF86Config-4:
                      o In the "Module" section, be sure that you have a line

                            Load "glx"

                        and remove or comment out (prepend with a #) any lines that refer to the "dri" or "GLCore" modules.
                      o In the "Device" section for your video card, be sure you have a line

                            Driver "nvidia"

                        An open-source alternative is the "nv" driver, which has 2D but no 3D capabilities.
         2. Create a "video" group, and add to it any users who should to be able to use the display. You can do this manually by editing /etc/group, or the Debian way by

                addgroup --system video
                adduser $USER video

            for each $USER you want to add to the group.
         3. Ensure that the nvidia module gets inserted into your kernel automatically at boot, by adding it to /etc/modules if it's not already there:

                grep -q ^nvidia /etc/modules || echo nvidia >> /etc/modules

That's it. Your binary driver and kernel interface module are now installed and configured, and should work when you reboot with the new kernel and/or restart your X server.


=== Load the kernel module and restart X ===
This is the easiest but probably most crucial step. If it doesn't work for some reason, and you want to get back to X before fixing the problem, you'll have to revert step 3 (by choosing a free X driver again). When you think you've fixed the problem, you can do step 3 again and retry starting X. Remember that even if it works you'll want to read the [next section to avoid future trouble. And if it doesn't...check the Troubleshooting section.

First, as your X is going to use the '''nvidia''' driver, it will need to have the '''nvidia''' kernel module loaded. You edited /etc/modules at step 3 to make sure that this module will load at boot time. But you probably didn't reboot since. To avoid rebooting your system instead of just restarting X, just load that module. You can do it that way:
{{{
# modprobe lsmod
}}}

Now to restart X. If you don't use a display manager, simply close your session. That should bring to a console. If it doesn't, you must be using a display manager (such as gdm, kdm or xdm). First identify which one you're using. If you don't know, it's probably gdm. You can know by checking whether a process ending with "dm" is running. Once you determined which one you use, close your session and go run the appropriate init script in a console. Here's an example for gdm:
{{{
# /etc/init.d/gdm restart
}}}
If you can't figure out how to restart X with those instructions, you can simply reboot your system. Otherwise, the keyboard shortcut Ctrl+Alt+Backspace should be reliable, despite being somewhat "unfriendly".

==== Check that it worked ====
To check that the acceleration is working, check if
{{{
$ glxinfo |grep rendering
}}}
returns "direct rendering: Yes". If it does, 3D acceleration (in games such as PlanetPenguin Racer and Neverball) should work. If it works in these games but not in a particular application you expected to be able to use, this application is probably buggy or doesn't support your system. This document probably can't help you with these problems.

=== How to deal with kernel changes and driver upgrades ===
Steps 2 and 3 are done for good. However, you'll have to repeat step 1 in certain situations. If you don't realize such a situation happens, X will fail to start. You can take two approaches with this : either remember when this will happen and try to prevent it, or remember to come back here when your X fails to start. Either way, you're not done for life. If X ever fails to starts because of this, you can again revert step 3 (by choosing a free X driver again) and redo it when you want to retry using the '''nvidia''' driver for X.

==== When ====
Step 1 builds an '''nvidia''' kernel module for a specific kernel and NVIDIA driver version. You'll have to do it for each kernel, and you'll have to redo it for each new driver version.
If you don't know what this means, read on.

===== ...will the NVIDIA driver version change =====
If you're using Sarge, this won't happen until you upgrade to the next Debian release, but it will happen then.

In all cases, this will happen when the nvidia-glx package is upgraded. All versions of nvidia-glx depend on an nvidia-kernel-'''version''' virtual package. When you followed step 1, you built or installed a package providing this virtual package. However, if you upgrade nvidia-glx before doing step 1 again, APT will attempt to satisfy the virtual package by installing a prebuilt kernel module. You'll notice some new nvidia-kernel-'''something''' package being installed (or upgraded if you already had it). This may be what you want if you're using a 2.4 kernel. If you're not, APT will be installing a useless package. Instead of letting it do, do step 1 again to get an appropriate kernel module. Then, the virtual package will be satisfied and you can upgrade nvidia-glx safely and without installing a useless package.

===== ...will your kernel change =====
If you build other modules using module-assistant, you have to redo step 1 everytime you'd have to run module-assistant for other modules, that is for every new kernel ABI. If you don't know what that means, read on.

If you use Sarge, this will most likely happen when you upgrade to 3.1r1. If not, it may happen in a later Sarge update. If it doesn't, it will happen when you upgrade to Etch.
This will also happen if you install a new kernel. For example, you can have both 2.4.27 and 2.6.8 in Sarge. If you did step 1 for 2.4.27 only, you'll need to do it for 2.6.8 too.
You'll notice that a new kernel is installed when a new kernel-image-'''something''' package is installed.

***contrib non-free***


= Troubleshooting =
== X doesn't start ==
 * Make sure the '''nvidia''' module is loaded into your kernel:
 {{{
 $ lsmod | grep nvidia
 }}}
 If it's not, then use modprobe or modconf to load it, or else have it load automatically at boot by adding nvidia to /etc/modules.

 * Check that you have device files /dev/nvidia0 and /dev/nvidiactl:
 {{{
 $ ls -l /dev/nvidia*
 crw-rw---- 1 root video 195, 0 date /dev/nvidia0
 crw-rw---- 1 root video 195, 255 date /dev/nvidiactl
 }}}

 * Make sure that your problem is related to the '''nvidia''' driver. Try switching back to a free driver: go back and repeat step 3, but this time select driver '''nv''' or '''vesa''' instead of '''nvidia'''. Then restart your X server. If it still won't start, then you have other problems that precede the NVIDIA's drivers.


== X (or the complete machine when running X) is unstable ==
 * Check whether you use a framebuffer, such as rivafb, nvidiafb and vesafb. The rivafb driver is known to conflict with NVIDIA's drivers. vesafb is known to work is some cases but also to be problematic in other cases. All of these drivers are compiled as modules in stock kernels, except for vesafb after 2.6.12. To see if you have one of these modules inserted in your kernel, run
 {{{
 $ lsmod|grep 'rivafb\|vesafb\|nvidiafb'
 }}}
 If this outputs something, get rid of the module(s) displayed.
 {{{
 # rmmod rivafb vesafb nvidiafb
 }}}
 will remove the modules temporarily (for this boot). If something causes one of the modules to load automatically at boot, blacklist the modules. If you are using a custom kernel, do not compile these modules in (Device drivers –> Graphics support –> nVidia Riva support (FB_RIVA), Device drivers –> Graphics support –> VESA VGA graphics support (FB_VESA) and Device drivers –> Graphics support –> nVidia Framebuffer Support (FB_NVIDIA)).

 * Several users have reported that they had hard lockups when switching virtual terminals or shutting down their X servers, until they recompiled their kernels with local APIC disabled. Local APIC support on uniprocessors (X86_UP_APIC) is enabled in stock non-SMP kernels. Note that the local APIC option isn't available if you have an SMP (e.g. hyperthreading) kernel. In that case the local APIC option probably has no effect, but one user reported that he still had success disabling it by manually editing /usr/src/linux/.config to comment out the line with CONFIG_X86_LOCAL_APIC. He also had to repeat the operation every time he reconfigured his kernel. Alternatively, you might have to turn off SMP and then disable local APIC. :(
## TODO: Verify SMP issue
 
== Various problems with X ==
Look in your X log file (/var/log/XFree86.0.log for XFree86, /var/log/Xorg.0.log for X.org). The X server writes a lot of information there about what configuration files it's reading, what display modes it's trying, and errors (EE) it encounters along the way. You can very often find hints there to the source of whatever problem you're having.

== "nvidia license taints kernel" ==

* If you get such a warning message on your console or in your syslog, don't worry. Your kernel is fine...or at least as fine as a kernel that can run NVIDIA's driver can be. All this message means is that because your driver isn't open source, you won't get any support from the kernel maintainers if anything goes wrong with your kernel while the module is loaded. See the [http://www.tux.org/lkml/#s1-18 LKML FAQ] for more.

== Some [old] game doesn't start ==
* If some software (probably old games) complains about missing libGL.so, try installing nvidia-glx-dev.
#Imported from Andrew's HOWTO, but not verified. The HOWTO red "thanks to Randall Donald for this information". --Filipus

== Last resort ==
You can check [http://www.nvnews.net/vbulletin/forumdisplay.php?f=14 the NVIDIA Linux Forum at nvnews.net]. If you still have a problem that you can't solve, you can write and tell me about it. I'll do what I can to help, subject to my knowledge and time constraints.
Line 44: Line 361:

= More information =
 * For more information about the nVidia driver, see:
  * /usr/share/doc/nvidia-glx/README.Debian
  * /usr/share/doc/nvidia-glx/README.gz
  * /usr/share/doc/nvidia-kernel-source/README.Debian
      These files have loads of information about options and troubleshooting for the nVidia driver. Here's an enticement for you to read them: somewhere in one of them you can find an explanation of how to suppress the nVidia splash screen every time you start an X server (hint: search for "NoLogo").
 * You can adjust the clock rates of your GPU and video RAM by running nvclock, nvclock_gtk, or nvclock_qt, available respectively in the nvclock, nvclock-gtk, and nvclock-qt packages. Obligatory warning: you can destroy your video hardware with these tools if you're not careful.
 * You can adjust some other, relatively obscure settings of the driver by running nvidia-settings, available in the nvidia-settings package.

This document explains how to make use of NVIDIA video hardware for ["Debian"] GNU/Linux users, who are the primary target. However, most (if not all) of Debian derivatives, including Libranet, Mepis, Ubuntu, and Xandros, should work in the same way. The following section shortly describes the ["free"] drivers while the rest of the document covers the ["non-free"] but 3D-accelerated drivers.

?TableOfContents

free drivers

Two free drivers in Debian support NVIDIA cards. You are probably reading this page using one of these drivers. The vesa driver is a generic video driver. You should get better results with the nv driver. You can see which one is in use ......................... You can simply [wiki:ConfigureX configure X] to change the free driver to use.

However, both of these drivers do not support 3D acceleration. Only the non-free nvidia driver supports this. If you are willing to use this driver despite the fact that it is non-free, read the following section. If you do, keep in mind that using the non-free drivers is considerably more complex and things are much more likely to break. If this happens and you give up trying to get X working again due to the nvidia driver, remember that simply switching back to one of the free drivers should let you run X again until you find a way to get 3D acceleration working again.

non-free drivers

Why a Debian-specific method?

To install the NVIDIA drivers, you can use either NVIDIA's official installer or the Debian driver packages. Each method has its advantages, as described below. NVIDIA's installer used to be easier to use; but with the advent of module-assistant, the Debian way is probably easier. Even if you choose to build your driver module manually, in the long run you'll probably find that the Debian way will save you work. The Debian way is of course the most reliable.

Unless you had issues with the Debian way, you probably just want to skip to the Installation section. NVIDIA's installer is already documented at other places (such as [http://www.gmpf.de/index.php/NVidia:Basic_Installation this one]), so the Installation section of this HOWTO is all about the Debian way. Either way, you may find the Troubleshooting section to be of interest.

Comparison of nvidia-installer and the Debian way

.............. The method described here is "the Debian way": you install Debian packages as usual, for your specific kernel. This method has some advantages, compared to using NVIDIA's official installer:

  • It's more automated, so it saves you work if you change your kernel.
  • It uses the Debian package management tools, so it's cleaner.
  • It can be done while X is running. You only have to restart X at the end, when you want the driver change to be applied.
  • If you're already using make-kpkg to build your kernel, it fits easily into your existing build procedure.
  • It will also save you work if you build other kernel modules (e.g. lm-sensors or fuse) outside of the kernel tree, because all of the driver packages get built at the same time with a single invocation of make-kpkg.
  • You won't need to download NVIDIA's official installer from nvidia.com. The Debian packages contain all of the parts of it that you need.

However, you don't have to build your drivers this way. Many people prefer just to get and run NVIDIA's official installer. This method also has advantages:

  • You may get more recent versions of the NVIDIA drivers, since the Debian packages tend to lag by a month or two, which can be needed if the version in Debian didn't support your hardware. You can compare the [http://www.nvidia.com/object/unix.html current version] and the [http://packages.debian.org/nvidia-glx version in your Debian release] to see how much difference there is.

  • The official installer is easy to use, although you will probably get tired of rerunning it if you rebuild your kernel more than a few times. (Every time you rebuild your kernel you have to wait until you reboot, wait for your X server to die, navigate the installer menus, and then start X. It gets old. That's why this guide was written :) ) Note: the Debian way is similarly easy.

  • You won't have to learn about module-assistant...wait, is this an advantage?
  • People have occasionally reported that even after some work, they just couldn't get their drivers to work using the Debian way. Once they used the NVIDIA installer everything worked smoothly.

Target audience

The following method should work with any 2.4 or 2.6 Linux kernel, with either stock or custom kernels, and with ["Sarge"], ["Etch"] and ["Sid"] (assuming Sid works). Although there are Debian packages for the drivers in ["Woody"], if you are looking to make some fun gaming, consider the fun of upgrading to Sarge first.

Installation

Here are the instructions for building and installing NVIDIA 3D drivers, the Debian way.

Overview

The NVIDIA driver consists of two parts: a kernel module, and a collection of user-space libraries. The libraries (sometimes called the "binary driver" or GLX libraries) are distributed in binary form by NVIDIA, and packaged for Debian in the nvidia-glx package. The kernel module (aka the "kernel interface to the binary driver") is distributed in source form (though with one binary component), and packaged for Debian in the nvidia-kernel-source and nvidia-kernel-common packages. The version of the kernel module has to match the version of the libraries. The user libraries and kernel module source only have to be installed once. Then the kernel module has to be rebuilt every time you change or rebuild your kernel. So, here's what you have to do:

  1. Build and install the kernel module.
  2. Install the user-space libraries.
  3. Configure X to use the nvidia driver and add the nvidia module to /etc/modules

Step 2 has to be performed after step 1 because of some dependencies, as explained below.

Steps 2 and 3 have to be performed only once. Step 1 has to be repeated every time you change your kernel, but with the help of module-assistant, apt-get, and make-kpkg, it's hardly any work at all. We'll come back to this at the end of the installation section.

Steps

Build and install the kernel module

Stock or Custom Kernel?

Some of the installation methods below depend on whether you're running a stock kernel, i.e. a prebuilt kernel from the Debian distribution. If you know which kind of kernel you have, you can skip to the following section.

By default, Debian comes with a stock kernel. If you don't know what kind of kernel you're running, then it's probably a stock kernel. If you're not sure, run

$ uname -r

and check if the output looks like 2.*.*-small number-architecture (e.g. 2.4.27-2-386 or 2.6.8-2-k7). If it does, you're most likely running a stock kernel.

Methods

There are four different methods that you can use to install the kernel module. If that sounds like a lot, don't worry—they're listed in order of difficulty. So start with the first one, and if it doesn't work for you, go on down the list.

Use module-assistant

This method is very easy, and should work for most people, with either a stock or custom kernel.

Install module-assistant if you don't have it, and nvidia-kernel-common. To do it with apt-get:

# apt-get install module-assistant nvidia-kernel-common 

Then run:

# m-a prepare
# m-a auto-install nvidia

And that's it. If all went well, your nvidia kernel module is now built and installed; you may proceed to step 2.

Note: you must use the same version of gcc to build your nvidia kernel module as was used to build your kernel. This might be a problem if you are running a stock kernel. If module-assistant fails, read its log output and look for messages suggesting that you need, for example, gcc-3.4 instead of gcc-3.3.

Install a pre-built module

This method is easy if you're running a recent stock kernel for which a pre-built module is available; it will not work at all if you're running a custom kernel. If the module-assistant method doesn't work for you and there are pre-built modules available for your kernel, use this method.

As of this writing, pre-built modules are only available for kernel 2.4.27, Sarge's default kernel. There are no pre-built modules for 2.6.8. If you don't know your kernel version, run

$ uname -r

If there is a pre-built module for your kernel, install its package (the name starts with "nvidia-kernel-". To do it with apt-get:

# apt-get install nvidia-kernel-$(uname -r)

If this step succeeds, you may now proceed to step 2. If not, try a different installation method.

Build manually, with a stock kernel

Use this method if you're running a stock kernel and the two previous methods failed or didn't apply to you. module-assistant should automate this process. In other words, if the first method failed but this one works, you should probably submit a bug report against module-assistant.

The following procedure is adapted from the instructions in /usr/share/doc/nvidia-kernel-source/README.Debian and is known to be potentially inexact.

  1. Save the release number of your kernel (e.g. 2.4.27-2-k7 or 2.6.8-1-686) in a couple of environment variables:
    • export KVERS=$(uname -r) export KSRC=/usr/src/kernel-headers-$KVERS
    • Note that these variables are used by the build commands below, so you really do need to set and export them, as in the above commands.
  2. Install the kernel module source: run
    • apt-get install nvidia-kernel-source nvidia-kernel-common
    • This will give you a source tarball /usr/src/nvidia-kernel-source.tar.gz. Unpack it with
      • cd /usr/src tar -zxf nvidia-kernel-source.tar.gz
      This will unpack the kernel module sources into /usr/src/modules/nvidia-kernel.
  3. Install the header files for your kernel:
    • apt-get install kernel-headers-$KVERS
    • This will give you kernel header files in /usr/src/kernel-headers-$KVERS. Be sure to check that the installed kernel image and kernel header packages have the same version number: run
      • apt-cache policy kernel-image-$KVERS kernel-headers-$KVERS
      and check that the version number listed as Installed is the same for both packages. If it isn't, find the distribution that has the version of kernel-headers that you need, e.g. testing, and rerun the above installation command, adding '-t testing' (or whichever).
  4. Build the kernel module package:
    • cd /usr/src/modules/nvidia-kernel debian/rules binary_modules
    • The result will be a package file /usr/src/nvidia-kernel-*.deb, which contains your kernel module. Note: several users have told me recently that their nvidia package file ends up in /usr/src/modules, instead of /usr/src. I don't know yet why this happens. If this is your case, please adjust the next command appropriately.
  5. Install the kernel module:
    • dpkg -i /usr/src/nvidia-kernel-*.deb
    • Use the fileglob as above if you want, but watch out that you don't have more than one nvidia-kernel package file lying around in /usr/src. If you do you'll get a blizzard of error messages. It's probably better to explicitly type all of the version information that I rendered as * above.
  • Now proceed to step 2, below.

Build manually, with a custom kernel

Use this method if you're configuring and building a custom kernel.

1. Install the kernel module source. To do it with apt-get:

# apt-get install nvidia-kernel-source nvidia-kernel-common

This will give you a source tarball /usr/src/nvidia-kernel-source.tar.gz. Unpack it with:

$ cd /usr/src
# tar -zxf nvidia-kernel-source.tar.gz 

This will unpack the kernel module sources into /usr/src/modules/nvidia-kernel.

2. Configure your kernel. This step isn't documented here; if you need to learn how, see the kernel-package documentation. But in summary, what you have to do is

$ cd /usr/src/linux
# make xconfig

and then choose the options you want. Note, however, that each of the following kernel options has been reported to cause trouble with the nvidia driver:

  • Graphics Support –> nVidia Riva support (FB_RIVA)

  • Processor Type and Features –> Local APIC support on uniprocessors (X86_UP_APIC) (not available if you have an SMP kernel, including hyperthreading)

It is therefore recommended that you disable all of the above options in your kernel configuration. If for some reason you don't disable them, and then your X display doesn't work properly with the nvidia driver, you should suspect these options as the likely cause of the trouble. For more details, see the troubleshooting page.

3. Build the kernel and the nvidia kernel module:

$ cd /usr/src/linux
# make-kpkg clean
# make-kpkg kernel_image modules_image

For an introduction to using make-kpkg to build kernel packages, see "Creating custom kernels with Debian's kernel-package system", or "Compiling Kernels the Debian Way". See also the make-kpkg man page, for a description of other options and targets that you can use in this command.

The result of the above command will be two Debian package files, { kernel | linux }-image-*.deb and nvidia-kernel-*.deb, both in /usr/src or /usr/src/modules. The first file contains your kernel, and the second contains your nvidia kernel module.

At the same time, if you have sources for any other add-on kernel modules in /usr/src/modules, then the "modules_image" target will cause make-kpkg to build Debian package files for them, too. For example, if you install the fuse-source package you'll get a source archive /usr/src/fuse.tar.gz, which you can unpack to get fuse module sources in /usr/src/modules/fuse. If you've done this, then this same invocation of make-kpkg will also build a fuse module package file, /usr/src/fuse-*.deb, that's specific to your new kernel.

4. Install the new kernel and kernel module:

$ cd /usr/src
# dpkg -i /path/kernel-image-*.deb /path/nvidia-kernel-*.deb

Use the fileglobs as above if you want, but watch out that you don't have more than one kernel-image or nvidia-kernel package file lying around in /usr/src. If you do you'll get a blizzard of error messages. It's probably better to explicitly type all of the version information rendered as * above.

Install the NVIDIA user-space libraries

Install the nvidia-glx package. To do it with apt-get:

# apt-get install nvidia-glx

Note

  • The reason this step has to come after step 1 is that nvidia-glx depends on a virtual package called 'nvidia-kernel-$NVVERSION', where $NVVERSION is the version number of the nvidia-glx package. This virtual package should be provided by the kernel module package that you installed in step 1; so you have to complete that step first.

Update your configuration

1. Update your X configuration. There are two ways to do this. The one you should use depends on whether you manually edited your X configuration file. If you don't know if you did, you probably didn't. To make sure, run one of the following commands, depending on your X server. Note that if you run Sarge and choose the debconf way but you did edit your X config file, your changes will be quietly ignored.

For XFree86 (Sarge):

$ md5sum /etc/X11/XF86Config-4|diff -sq /var/lib/xfree86/XF86Config-4.md5sum -

For X.org (Etch):

$ md5sum /etc/X11/xorg.conf|diff -sq /var/lib/xfree86/xorg.conf.md5sum -

If the files differ, choose the second way (the manual way).

The debconf way

As a suggestion, save yourself some possible grief later by backing up your current X config file. For XFree86 (Sarge):

# cp -p /etc/X11/XF86Config-4 /etc/X11/XF86Config-4.bak

For X.org (Etch):

# cp -p /etc/X11/xorg.conf /etc/X11/xorg.conf.bak

2. Tell Debian that XF86Config-4 has never been edited:

  • md5sum /etc/X11/XF86Config-4 >| /var/lib/xfree86/XF86Config-4.md5sum

  • If you don't perform this step, and you have ever edited XF86Config-4, then dpkg-reconfigure will lead you through its whole questionnaire below, and then silently fail to write a new XF86Config-4. This is Debian bug #223929.

Run the following command. For XFree86 (Sarge):

# dpkg-reconfigure xserver-xfree86

For X.org (Etch):

# dpkg-reconfigure xserver-xorg

This will ask you a long series of questions that you should have already seen at least when you installed Debian. You only need to change your answer to 2 of those questions. When asked to choose an X server driver, choose nvidia. Then, when asked to select X server modules, deselect (uncheck) GLCore and dri, and select (check) glx.

Finally, if you use Sarge, you may want to verify that your X config file was written. To do so, run:

$ ls -l /etc/X11/XF86Config-4

and check that the date printed is current.

The manual way

This method will preserve any customizations you've made to XF86Config-4. Just watch out for typos, and check /var/log/XFree86.0.log if you've recently edited XF86Config-4 and things go wrong.

  • Edit /etc/X11/XF86Config-4:
    • o In the "Module" section, be sure that you have a line
      • Load "glx"
      • and remove or comment out (prepend with a #) any lines that refer to the "dri" or "GLCore" modules.
      o In the "Device" section for your video card, be sure you have a line
      • Driver "nvidia"
      • An open-source alternative is the "nv" driver, which has 2D but no 3D capabilities.
  1. Create a "video" group, and add to it any users who should to be able to use the display. You can do this manually by editing /etc/group, or the Debian way by
    • addgroup --system video adduser $USER video
    • for each $USER you want to add to the group.
  2. Ensure that the nvidia module gets inserted into your kernel automatically at boot, by adding it to /etc/modules if it's not already there:
    • grep -q ^nvidia /etc/modules || echo nvidia >> /etc/modules

That's it. Your binary driver and kernel interface module are now installed and configured, and should work when you reboot with the new kernel and/or restart your X server.

Load the kernel module and restart X

This is the easiest but probably most crucial step. If it doesn't work for some reason, and you want to get back to X before fixing the problem, you'll have to revert step 3 (by choosing a free X driver again). When you think you've fixed the problem, you can do step 3 again and retry starting X. Remember that even if it works you'll want to read the [next section to avoid future trouble. And if it doesn't...check the Troubleshooting section.

First, as your X is going to use the nvidia driver, it will need to have the nvidia kernel module loaded. You edited /etc/modules at step 3 to make sure that this module will load at boot time. But you probably didn't reboot since. To avoid rebooting your system instead of just restarting X, just load that module. You can do it that way:

# modprobe lsmod

Now to restart X. If you don't use a display manager, simply close your session. That should bring to a console. If it doesn't, you must be using a display manager (such as gdm, kdm or xdm). First identify which one you're using. If you don't know, it's probably gdm. You can know by checking whether a process ending with "dm" is running. Once you determined which one you use, close your session and go run the appropriate init script in a console. Here's an example for gdm:

# /etc/init.d/gdm restart

If you can't figure out how to restart X with those instructions, you can simply reboot your system. Otherwise, the keyboard shortcut Ctrl+Alt+Backspace should be reliable, despite being somewhat "unfriendly".

Check that it worked

To check that the acceleration is working, check if

$ glxinfo |grep rendering

returns "direct rendering: Yes". If it does, 3D acceleration (in games such as ?PlanetPenguin Racer and Neverball) should work. If it works in these games but not in a particular application you expected to be able to use, this application is probably buggy or doesn't support your system. This document probably can't help you with these problems.

How to deal with kernel changes and driver upgrades

Steps 2 and 3 are done for good. However, you'll have to repeat step 1 in certain situations. If you don't realize such a situation happens, X will fail to start. You can take two approaches with this : either remember when this will happen and try to prevent it, or remember to come back here when your X fails to start. Either way, you're not done for life. If X ever fails to starts because of this, you can again revert step 3 (by choosing a free X driver again) and redo it when you want to retry using the nvidia driver for X.

When

Step 1 builds an nvidia kernel module for a specific kernel and NVIDIA driver version. You'll have to do it for each kernel, and you'll have to redo it for each new driver version. If you don't know what this means, read on.

...will the NVIDIA driver version change

If you're using Sarge, this won't happen until you upgrade to the next Debian release, but it will happen then.

In all cases, this will happen when the nvidia-glx package is upgraded. All versions of nvidia-glx depend on an nvidia-kernel-version virtual package. When you followed step 1, you built or installed a package providing this virtual package. However, if you upgrade nvidia-glx before doing step 1 again, APT will attempt to satisfy the virtual package by installing a prebuilt kernel module. You'll notice some new nvidia-kernel-something package being installed (or upgraded if you already had it). This may be what you want if you're using a 2.4 kernel. If you're not, APT will be installing a useless package. Instead of letting it do, do step 1 again to get an appropriate kernel module. Then, the virtual package will be satisfied and you can upgrade nvidia-glx safely and without installing a useless package.

...will your kernel change

If you build other modules using module-assistant, you have to redo step 1 everytime you'd have to run module-assistant for other modules, that is for every new kernel ABI. If you don't know what that means, read on.

If you use Sarge, this will most likely happen when you upgrade to 3.1r1. If not, it may happen in a later Sarge update. If it doesn't, it will happen when you upgrade to Etch. This will also happen if you install a new kernel. For example, you can have both 2.4.27 and 2.6.8 in Sarge. If you did step 1 for 2.4.27 only, you'll need to do it for 2.6.8 too. You'll notice that a new kernel is installed when a new kernel-image-something package is installed.

***contrib non-free***

Troubleshooting

X doesn't start

  • Make sure the nvidia module is loaded into your kernel:

     $ lsmod | grep nvidia
    If it's not, then use modprobe or modconf to load it, or else have it load automatically at boot by adding nvidia to /etc/modules.
  • Check that you have device files /dev/nvidia0 and /dev/nvidiactl:
     $ ls -l /dev/nvidia*
     crw-rw----    1 root     video    195,   0 date /dev/nvidia0
     crw-rw----    1 root     video    195, 255 date /dev/nvidiactl
  • Make sure that your problem is related to the nvidia driver. Try switching back to a free driver: go back and repeat step 3, but this time select driver nv or vesa instead of nvidia. Then restart your X server. If it still won't start, then you have other problems that precede the NVIDIA's drivers.

X (or the complete machine when running X) is unstable

  • Check whether you use a framebuffer, such as rivafb, nvidiafb and vesafb. The rivafb driver is known to conflict with NVIDIA's drivers. vesafb is known to work is some cases but also to be problematic in other cases. All of these drivers are compiled as modules in stock kernels, except for vesafb after 2.6.12. To see if you have one of these modules inserted in your kernel, run
     $ lsmod|grep 'rivafb\|vesafb\|nvidiafb'
    If this outputs something, get rid of the module(s) displayed.
     # rmmod rivafb vesafb nvidiafb

    will remove the modules temporarily (for this boot). If something causes one of the modules to load automatically at boot, blacklist the modules. If you are using a custom kernel, do not compile these modules in (Device drivers –> Graphics support –> nVidia Riva support (FB_RIVA), Device drivers –> Graphics support –> VESA VGA graphics support (FB_VESA) and Device drivers –> Graphics support –> nVidia Framebuffer Support (FB_NVIDIA)).

  • Several users have reported that they had hard lockups when switching virtual terminals or shutting down their X servers, until they recompiled their kernels with local APIC disabled. Local APIC support on uniprocessors (X86_UP_APIC) is enabled in stock non-SMP kernels. Note that the local APIC option isn't available if you have an SMP (e.g. hyperthreading) kernel. In that case the local APIC option probably has no effect, but one user reported that he still had success disabling it by manually editing /usr/src/linux/.config to comment out the line with CONFIG_X86_LOCAL_APIC. He also had to repeat the operation every time he reconfigured his kernel. Alternatively, you might have to turn off SMP and then disable local APIC. :(

Various problems with X

Look in your X log file (/var/log/XFree86.0.log for XFree86, /var/log/Xorg.0.log for X.org). The X server writes a lot of information there about what configuration files it's reading, what display modes it's trying, and errors (EE) it encounters along the way. You can very often find hints there to the source of whatever problem you're having.

"nvidia license taints kernel"

* If you get such a warning message on your console or in your syslog, don't worry. Your kernel is fine...or at least as fine as a kernel that can run NVIDIA's driver can be. All this message means is that because your driver isn't open source, you won't get any support from the kernel maintainers if anything goes wrong with your kernel while the module is loaded. See the [http://www.tux.org/lkml/#s1-18 LKML FAQ] for more.

Some [old] game doesn't start

* If some software (probably old games) complains about missing libGL.so, try installing nvidia-glx-dev. #Imported from Andrew's HOWTO, but not verified. The HOWTO red "thanks to Randall Donald for this information". --Filipus

Last resort

You can check [http://www.nvnews.net/vbulletin/forumdisplay.php?f=14 the NVIDIA Linux Forum at nvnews.net]. If you still have a problem that you can't solve, you can write and tell me about it. I'll do what I can to help, subject to my knowledge and time constraints.

About this document

The Links page has links to nVidia driver packages, support forums, other HOWTOs, and anything else I find that can help you to get your nVidia hardware working under Debian.

For problems, comments, or questions about the information in this HOWTO, you can write to me. I'm no expert, but I'll do my best to make the information useful.

More information

  • For more information about the nVidia driver, see:
    • /usr/share/doc/nvidia-glx/README.Debian
    • /usr/share/doc/nvidia-glx/README.gz
    • /usr/share/doc/nvidia-kernel-source/README.Debian
      • These files have loads of information about options and troubleshooting for the nVidia driver. Here's an enticement for you to read them: somewhere in one of them you can find an explanation of how to suppress the nVidia splash screen every time you start an X server (hint: search for "?NoLogo").

  • You can adjust the clock rates of your GPU and video RAM by running nvclock, nvclock_gtk, or nvclock_qt, available respectively in the nvclock, nvclock-gtk, and nvclock-qt packages. Obligatory warning: you can destroy your video hardware with these tools if you're not careful.
  • You can adjust some other, relatively obscure settings of the driver by running nvidia-settings, available in the nvidia-settings package.