Andrew's Debian-nVidia HOWTO

This document explains how to build and install drivers for nVidia video hardware under Debian GNU/Linux, or any of its derivatives including Libranet, Mepis, Ubuntu, or Xandros. The method works with any 2.4- or 2.6-series Linux kernel, and with either stock or custom kernels.

To install the nVidia drivers, you can use either an official installer from nVidia, or the Debian driver packages. Each method has its advantages, as I describe below. The official installer used to be easier to use; but with the advent of module-assistant, they're about equally easy, or the Debian way may even be 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 official installer is pretty self-explanatory, 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.

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.

The Debian Way vs. the nVidia Installer

The method that I describe here is "the Debian way": you build package files (*.deb) for your kernel and driver, and then install them as usual using dpkg or apt-get. This method has some advantages, compared to using the official nVidia installer:

• 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 nVidia packages and package management tools, so it's cleaner and makes use of what you already know about these tools.
• 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 (although that's a pretty short lag for Debian packages). (Compare the nVidia and Debian unstable version numbers to see how much difference there is today.)
• 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 I wrote this HOWTO :)
• You won't have to learn about module-assistant, or make-kpkg. Wait, is this an advantage?
• People have occasionally reported to me 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.

For me, the Debian way works best with this driver. Use the method that works best for you. 

Installation

Here are the instructions for building and installing your nVidia 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 user libraries and kernel module source only have to be installed once. Then the kernel module has to be rebuilt every time you rebuild or change your kernel. So, here's what you will do:

1. Build and install the kernel module.
2. Install the user-space libraries.
3. Update your configuration.

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

Steps 2 and 3 have to be performed only once. Step 1 you have to repeat 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.

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 don't know what kind of kernel you're running, then it's probably a stock kernel. But to find out, run

apt-cache policy kernel-image-$(uname -r)

and look at the source lines for the version that's listed as installed. If the source lines include something at debian.org, then you're running a stock kernel. If no version is listed as installed, then you're running a custom kernel. If a version is installed, but the only source listed for the installed version is /var/lib/dpkg/status, then you may be running a custom kernel, or a stock kernel that's old enough to have dropped out of the Debian distribution. The easiest way to tell is just to look at the kernel version number (output of uname -r): if it looks like e.g. 2.4.x-1-k7 or 2.6.x-1-686, then it's probably an old stock kernel.

Choose a Distribution

Before you install the Debian nVidia packages, you should choose a distribution, either 'testing' or 'unstable', from which to install them. There is no 'stable' version of these packages at present. You can run 'apt-cache policy nvidia-kernel-source' to see which versions of the driver are available in each distribution.

Once you've chosen a distribution, put its value into a shell variable NVDIST, by executing one of the following lines:

NVDIST=testing
NVDIST=unstable

I will use $NVDIST to represent this value in all of the commands below. Also, make sure that your /etc/apt/sources.list contains a line like 'deb http://http.us.debian.org/debian $NVDIST main contrib non-free', for your $NVDIST. (Help yourself to a copy of my sources.list if you like.) And if you've just modified /etc/apt/sources.list, you need to run 'apt-get update' before continuing below.

Installation Instructions

1. Build and install the kernel module.
   There are four different procedures that you can use to install the kernel module. If that sounds like a lot, don't worry—I've listed the easiest methods first. So start with the first one, and if it doesn't work for you, go on down the list. Click on the title of each method to see the instructions.
   • 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:

     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 .
     module-assistant automates the more detailed procedures described below: it downloads the nvidia kernel module source, builds a kernel module package compatible with your (stock or custom) kernel, and installs the package. (If you're interested, the package file is /usr/src/nvidia-kernel-*.deb, and you can see that it's installed by running apt-cache policy nvidia-kernel-$(uname -r).) Of course module-assistant has many other operations and options; see the man page for details.
     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. (Thanks to Josep Ma Antolin for this tip.)
   • Install a pre-built module. This method is easy if you're running a recent stock kernel ; will take a little more work and may fail if you're running an older stock kernel; and will not work at all if you're running a custom kernel .
      
     1. Find out if there's a prebuilt module available for your kernel. The official Debian mirrors include prebuilt modules for just a few stock kernels, but Randall Donald maintains unofficial prebuilt modules for many other old and current stock kernels. To get access to Randall's repository, add

        deb http://people.debian.org/~rdonald/nvidia modules-unstable/i386/

        into your /etc/apt/sources.list. Now run

        apt-get update
apt-cache policy nvidia-kernel-$(uname -r)

        and look for a source line somewhere at debian.org. If there is one, then proceed to step (b). If you don't find one, then there's no prebuilt module for your kernel, so this installation method won't work for you; you should go ahead and try a different installation method.
     2. Find out if there are nvidia-glx and nvidia-kernel-common packages compatible with your nvidia-kernel-* package: run

        apt-cache policy nvidia-kernel-$(uname -r) nvidia-glx nvidia-kernel-common

        and look for versions of all three packages with compatible version numbers (identical up to the first - or +). If you find them, you're in luck; proceed to step (c).
        If you don't find compatible versions of all three nvidia-* packages, then you may still be able to find some on backports.org : search there for nvidia, add the lines it tells you about to your /etc/apt/sources.list, run apt-get update, and repeat this step.
        If after trying the above you still can't find compatible versions of the three nvidia-* packages, then sorry, but this installation method will not work for you. You should go another method. As a rule, nvidia-kernel-* packages are only available in the versions of the nvidia driver that were current at the same time as the kernels they were built for; while nvidia-glx is generally only available in the latest one or two versions. For example, at this writing nvidia-kernel-2.6.3-1-386 is only available in version 1.0.5336, while nvidia-glx is only available in version 1.0.7174. Those versions are incompatible, so if your kernel is a stock 2.6.3, then you have to either upgrade it or choose a different installation method for the nVidia drivers.
     3. If you found compatible nvidia-* packages in steps (a) and (b), then install them now:

        apt-get -t $NVDIST install nvidia-kernel-common nvidia-kernel-$(uname -r)

        (you'll install nvidia-glx below). You may have to adjust $NVDIST here, depending on where you found compatible versions of the nVidia packages in step (b), above. Sorry, but the possible permutations are too numerous to list here. 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 want or need to build your own nVidia kernel module or other add-on kernel modules.
     (The following procedure is adapted from the instructions in /usr/share/doc/nvidia-kernel-source/README.Debian.)
     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 -t $NVDIST 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: run

        apt-get -t $NVDIST 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. I won't try to document this step here; if you need to learn how, see the Kernel HOWTO and "How to Upgrade to the 2.6 Kernel" . But in summary, all 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 drivers:
        • Graphics Support –> nVidia Riva support (FB_RIVA)
        • Kernel Hacking –> Use 4Kb for kernel stacks instead of 8Kb (4KSTACKS)
        • Processor Type and Features –> Local APIC support on uniprocessors (X86_UP_APIC) (not available if you have an SMP kernel, including hyperthreading)
        I therefore recommend 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 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-image-*.deb and nvidia-kernel-*.deb, both in /usr/src. 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.
        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 following commands appropriately.
     4. Install the new kernel and kernel module:

        cd /usr/src
dpkg -i kernel-image-*.deb 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 that I rendered as * above.
2. Install the nVidia user-space libraries. Run

   apt-get -t $NVDIST install nvidia-glx

   If you're asked whether you want to install the thread-local storage libraries, say yes. Notes:
   • If the kernel you installed above is version 2.6.x, and the one you're running now is pre-2.6, then you should reboot with your new kernel before performing this step. The reason is that if you're not running a 2.6-series kernel when you perform this step, the thread-local storage part of the user-space libraries will not be installed. As a result your X server will crash when it tries to load the nVidia driver. If you already installed nvidia-glx earlier under a pre-2.6 kernel, then reboot to the new kernel, run dpkg-reconfigure nvidia-glx, and answer yes when asked if you want to install the TLS libraries.
   • 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 driver you've installed. This virtual package is provided by the kernel module package that you installed in step 1; so you have to complete that step first.
3. Update your configuration.
   1. Update /etc/X11/XF86Config-4. Naturally, there is both a Debian way and an old-fashioned way of doing this. Click on a method title to see the instructions.
       
      • The Debian way. This method avoids many common configuration errors, because you don't write an XF86Config-4 file yourself. Instead you answer a series of questions about your mouse, keyboard, and video hardware, and then the configuration script writes an XF86Config-4 file for you.
         
        1. Save yourself some possible grief later, by backing up your current XF86Config-4:

           cp -p /etc/X11/XF86Config-4 /etc/X11/XF86Config-4.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 .
        3. Run

           dpkg-reconfigure xserver-xfree86

           and answer all of the questions.
        4. When asked to choose an X server driver, choose "nvidia". An open-source alternative is the "nv" driver , which has 2D but no 3D capabilities.
        5. When asked to select X server modules, deselect (uncheck) GLCore and dri, and select (check) glx.
        When you're done, ls -l /etc/X11/XF86Config-4 to be sure your new XF86Config-4 file has been written. Thanks to Dave Page for informing me about this method.
      • The manual way. This method is simpler, and it 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:
        • 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.
        • 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 you want 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.

Notes

• Of course the nvidia module will have to be loaded into your kernel to work. If you've just installed the driver and don't need to reboot, then load the driver manually with modprobe nvidia or modconf before restarting your X server.
• 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.
• As I said above, you won't ever have to repeat steps 2 and 3 above, as long as you don't reverse them, of course.
• On the other hand, the kernel module that you built in step 1 is specific to the kernel you built it with. If you install a new kernel that's different in any way from the old one, you'll have to install a new driver module to go with it. In that case just go back and repeat step 1.
• Using this method, you don't need any of the following things:
  • The official nVidia installer from nvidia.com. The Debian packages contain all of the parts of it that you need.
  • Any of the patch or installer files available at minion.de . (But thanks to the folks at minion.de for providing those patches, during all of the time when the official nVidia drivers didn't work yet with kernel 2.6.)
  • The nvidia-kernel-src and nvidia-glx-src packages, which are deprecated. You can also ignore the nvidia-glx-dev package, unless you get complaints from some software (old games?) about missing libGL.so (thanks to Randall Donald for this information).
• You can ignore the warning at www.minion.de about carrying along the EXTRAVERSION information if you use --append-to-version with make-kpkg. Because you're using make-kpkg all the way through the build process, it takes care of this for you.
• If you have problems, see the Troubleshooting page .

Troubleshooting

Your kernel module won't build.

• If your kernel is version 2.6.5, you probably ran "make clean" after building the kernel. Starting in kernel 2.6.5, "make clean" has become more aggressive, so that it now removes some of the files you need in order to build your nvidia module (and apparently some other modules as well, including the ones in VMware). This is Debian bug #242038 . Note that "make clean" may run automatically after the kernel build, without you necessarily asking for it or noticing it. There are several possible solutions:
  • Run

    cd /usr/src/linux
make include/linux/version.h

    (thanks to Roberto Sanchez for this tip).
  • If you use "make-kpkg kernel_image" to build your kernel, you can prevent the "make clean" from running by adding a line

    do_clean := NO

    in /etc/kernel-pkg.conf. Now rerun "make-kpkg kernel_image".
  • Upgrade your kernel to a more recent version, and/or upgrade your kernel-package package to the testing or unstable version. The problem apparently has been fixed in more recent kernels, and also in later versions of kernel-package by setting do_clean:=NO by default.
  After any of the above steps, you should now be able to build your nvidia module.

You can build and install the drivers, but your X display won't function properly or at all after you reboot.

• If you first installed the nvidia-glx package while running kernel 2.4, the thread-local storage libraries in the package were not installed at that time. If you're now running kernel 2.6, then your driver will fail as a result, causing your X server to die with the opaque error message "Server caught signal 11". The solution is to run 'dpkg-reconfigure nvidia-glx' while running kernel 2.6. (Thanks to Alberto Guzmán for this tip.)
• If you've just upgraded to kernel 2.6, make sure you've installed the module-init-tools package, which replaces the old modutils package, for loading kernel modules. If you don't do this, none of your kernel modules will load, including nvidia, so (among other problems) your X display won't start. For this and other information, you really must read "How to Upgrade to the 2.6 Kernel" .
• 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/nvidia*:
  $ ls -l /dev/nvidia* crw-rw---- 1 root video 195, 0 Nov 10 03:59 /dev/nvidia0 crw-rw---- 1 root video 195, 1 Nov 10 03:59 /dev/nvidia1 crw-rw---- 1 root video 195, 2 Nov 10 03:59 /dev/nvidia2 crw-rw---- 1 root video 195, 3 Nov 10 03:59 /dev/nvidia3 crw-rw---- 1 root video 195, 4 Nov 10 03:59 /dev/nvidia4 crw-rw---- 1 root video 195, 5 Nov 10 03:59 /dev/nvidia5 crw-rw---- 1 root video 195, 6 Nov 10 03:59 /dev/nvidia6 crw-rw---- 1 root video 195, 7 Nov 10 03:59 /dev/nvidia7 crw-rw---- 1 root video 195, 255 Nov 10 03:59 /dev/nvidiactl
  If you don't have them, it's probably because you're running udev or devfs. In any case, the simplest way to fix this problem is to upgrade to a recent version of the nvidia-kernel-common package, which includes a boot script (/etc/init.d/nvidia-kernel) that recreates these devices after every reboot. The boot script is present in version 20051028+1, at least, of nvidia-kernel-common. Once you've upgraded nvidia-kernel-common, you can either reboot or just run /etc/init.d/nvidia-kernel start to create the device files.
• Since kernel 2.6.5-mm?, there is a kernel option called 4KSTACKS which is incompatible with the nVidia driver, and will cause it to crash. Turn it off:
  • If your kernel is version 2.6.5-mm?, 4KSTACKS isn't part of the regular kernel .config file; to turn it off you have to edit /usr/src/linux/arch/i386/Kconfig, find "config 4KSTACKS", and change the "def_bool y" that follows to "def_bool n". (Thanks to Antti Kumar for this description.)
  • In kernel 2.6.6 or later, CONFIG_4KSTACKS is a regular kernel option, which you can find in the kernel config under Kernel hacking –> Use 4Kb for kernel stacks.
  Then rebuild your kernel and nvidia module. Note: I have no experience with this. I'm just passing along what many people have reported either in the newsgroups or directly to me. Has this problem been fixed in the latest nVidia drivers?
• Kernel 2.6.9 has some particular problems with nVidia drivers:
  • If loading your nvidia kernel module fails with an error message "Unknown symbol VMALLOC_RESERVE", then you need to apply this patch to your kernel source. Download and save the patch into /usr/src, then run

    cd /usr/src/linux
patch -p1 < ../nvidia-vmalloc-reserve.patch

    Then rebuild and reinstall your kernel and nVidia driver, and try again. I've been told that this problem only occurs with nVidia driver version 1.0.6111.
  • Many people have reported ( 1 , 2 , 3 ) that the combination of a Riva TNT2 video card with kernel 2.6.9 and nVidia driver 1.0.6629 gives them a black screen, or a screen with garbage. The workaround is to go back to driver 1.0.6111. There's reason to believe that this problem has been fixed in the driver development code, so it should be fixed in the next release. Thanks to Hugo Vanvoerkom for reporting this problem.
• Kernel 2.6.10 apparently also has some particular problems with nVidia drivers versions 1.0.6111 and 1.0.6629:
  • You will need to apply the VMALLOC_RESERVE patch .
  • If loading your nvidia kernel module fails with an error message "Unknown symbol pci_find-class", then you need to apply this patch to your kernel source. Download and save the patch into /usr/src, then run

    cd /usr/src/linux
patch -p1 < ../nvidia-pci-find-class.patch

  • Some people have reported "kernel oopses" or black screens that were solved by this patch . Download and save it into /usr/src, then run

    cd /usr/src/modules/nvidia-kernel/nv
patch -p3 < /usr/src/nvidia-kernel-2.6.10.patch

  After applying these patches, rebuild and reinstall your kernel and nVidia driver and try again. Thanks to Stéphane Huc for reporting these issues to me.
• The rivafb kernel module is known to be incompatible with the nVidia driver; see /usr/share/doc/nvidia-kernel-source/README.Debian . To see if you have this module inserted in your kernel, run 'lsmod | grep rivafb' . If you do, then get rid of it by, in increasing order of forcefulness: 'rmmod rivafb'; 'rm /lib/modules/`uname -r`/kernel/drivers/video/riva/rivafb.ko'; or disabling the module in your kernel config (Device drivers –> Graphics support –> nVidia Riva) and rebuilding your kernel. (If you still want a framebuffer driver, try VESA VGA; it's slow but works well.)
• Newer kernels (≥2.6.12 or so) also have an nVidia framebuffer option (FB_NVIDIA; nvidiafb module). I haven't tried this, but the same advice applies as with rivafb: don't use it. It will probably conflict with the nVidia non-free driver. If you want framebuffer support, use VESA VGA instead.
• Several users have reported to me that they had hard lockups when switching virtual terminals or shutting down their X servers, until they recompiled their kernels with local APIC disabled. 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. :(
• One user reports that his screen stayed black until he loaded the "unix" kernel module, since his X server couldn't connect to Unix-domain sockets.
• One user reports that his X server wouldn't start until he removed the Chipset option from the Device section for his video card in /etc/X11/XF86Config-4.
• One user reports that he had hard lockups every time X started, until he found and removed the file /usr/X11R6/lib/modules/drivers/nvidia_drv.so.
• Look in /var/log/XFree86.0.log. 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.
• Try switching to the nv driver: go back and repeat step 3a , but this time select driver "nv" instead of "nvidia". Then restart your X server. If it still won't start, then you have other problems that precede the nVidia driver. (Try apt-get install x-window-system-core to make sure you have a minimal functioning X setup.)
• Read the README files that I mention at the end of the Installation section. They have a lot of useful information about the driver.
• The Debian X Window System FAQ lists solutions to many common problems in getting your X server to work with your hardware.
• You can try searching or posting to the nVidia-Linux forum at nvnews.net.

Hardware acceleration, aka direct rendering, doesn't work.

You can detect this by running

glxinfo | grep "direct rendering"

If the answer is No, then you're using software acceleration for 3D. That means that your CPU is doing the work that your GPU should be doing, so with any recent video hardware, you're getting poorer frame rates and higher CPU utilization than your hardware permits. To correct this:

• Be sure that you've installed the nvidia-glx package.
• Be sure that you've adjusted your X server configuration, as I describe on the installation page .
• You may be using different client and server versions of GLX, due to incorrectly installed symlinks. This is Debian bug #208198 . Run

  glxinfo | egrep "glx (vendor|version)"

  and if you see different vendors or versions for the client and server, this is your problem. In that case run

   

  ln -fs /usr/lib/libGL.so.$NVVER /usr/X11R6/lib/libGL.so ln -fs /usr/lib/libGL.so.$NVVER /usr/X11R6/lib/libGL.so.1 ln -fs libGL.so.$NVVER /usr/lib/libGL.so.1.2

  where $NVVER is the version of your nvidia-glx package, e.g. 1.0.7174 as of this writing in stable, testing, and unstable.

After taking any of the above steps you'll have to restart your X server to get hardware acceleration working. But before you do that, run glxgears for a while and take note of the frame rates. Then check them again after you restart with hardware acceleration—my frame rates jumped from 570 to 3750/s.

You get a warning message on your console or in your syslog, saying "nvidia license taints kernel".

• Don't worry. Your kernel is fine. 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 LKML FAQ for more.

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.

This document explains how to build and install drivers for nVidia video hardware under Debian GNU/Linux, or any of its derivatives including Libranet, Mepis, Ubuntu, or Xandros. The method works with any 2.4- or 2.6-series Linux kernel, and with either stock or custom kernels.

To install the nVidia drivers, you can use either an official installer from nVidia, or the Debian driver packages. Each method has its advantages, as I describe below . The official installer used to be easier to use; but with the advent of module-assistant , they're about equally easy, or the Debian way may even be 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 official installer is pretty self-explanatory, 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.

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.

The Debian Way vs. the nVidia Installer

The method that I describe here is "the Debian way": you build package files (*.deb) for your kernel and driver, and then install them as usual using dpkg or apt-get. This method has some advantages, compared to using the official nVidia installer:

• 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 nVidia packages and package management tools, so it's cleaner and makes use of what you already know about these tools.
• 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 (although that's a pretty short lag for Debian packages). (Compare the nVidia and Debian unstable version numbers to see how much difference there is today.)
• 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 I wrote this HOWTO :)
• You won't have to learn about module-assistant, or make-kpkg. Wait, is this an advantage?
• People have occasionally reported to me 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.

For me, the Debian way works best with this driver. Use the method that works best for you. 

Installation

Here are the instructions for building and installing your nVidia 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 user libraries and kernel module source only have to be installed once. Then the kernel module has to be rebuilt every time you rebuild or change your kernel. So, here's what you will do:

1. Build and install the kernel module.
2. Install the user-space libraries.
3. Update your configuration.

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

Steps 2 and 3 have to be performed only once. Step 1 you have to repeat 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.

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 don't know what kind of kernel you're running, then it's probably a stock kernel. But to find out, run

apt-cache policy kernel-image-$(uname -r)

and look at the source lines for the version that's listed as installed. If the source lines include something at debian.org, then you're running a stock kernel. If no version is listed as installed, then you're running a custom kernel. If a version is installed, but the only source listed for the installed version is /var/lib/dpkg/status, then you may be running a custom kernel, or a stock kernel that's old enough to have dropped out of the Debian distribution. The easiest way to tell is just to look at the kernel version number (output of uname -r): if it looks like e.g. 2.4.x-1-k7 or 2.6.x-1-686, then it's probably an old stock kernel.

Choose a Distribution

Before you install the Debian nVidia packages, you should choose a distribution, either 'testing' or 'unstable', from which to install them. There is no 'stable' version of these packages at present. You can run 'apt-cache policy nvidia-kernel-source' to see which versions of the driver are available in each distribution.

Once you've chosen a distribution, put its value into a shell variable NVDIST, by executing one of the following lines:

NVDIST=testing
NVDIST=unstable

I will use $NVDIST to represent this value in all of the commands below. Also, make sure that your /etc/apt/sources.list contains a line like 'deb http://http.us.debian.org/debian $NVDIST main contrib non-free', for your $NVDIST. (Help yourself to a copy of my sources.list if you like.) And if you've just modified /etc/apt/sources.list, you need to run 'apt-get update' before continuing below.

Installation Instructions

1. Build and install the kernel module.
   There are four different procedures that you can use to install the kernel module. If that sounds like a lot, don't worry—I've listed the easiest methods first. So start with the first one, and if it doesn't work for you, go on down the list. Click on the title of each method to see the instructions.
   • 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:

     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 .
     module-assistant automates the more detailed procedures described below: it downloads the nvidia kernel module source, builds a kernel module package compatible with your (stock or custom) kernel, and installs the package. (If you're interested, the package file is /usr/src/nvidia-kernel-*.deb, and you can see that it's installed by running apt-cache policy nvidia-kernel-$(uname -r).) Of course module-assistant has many other operations and options; see the man page for details.
     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. (Thanks to Josep Ma Antolin for this tip.)
   • Install a pre-built module. This method is easy if you're running a recent stock kernel ; will take a little more work and may fail if you're running an older stock kernel; and will not work at all if you're running a custom kernel .
      
     1. Find out if there's a prebuilt module available for your kernel. The official Debian mirrors include prebuilt modules for just a few stock kernels, but Randall Donald maintains unofficial prebuilt modules for many other old and current stock kernels. To get access to Randall's repository, add

        deb http://people.debian.org/~rdonald/nvidia modules-unstable/i386/

        into your /etc/apt/sources.list. Now run

        apt-get update
apt-cache policy nvidia-kernel-$(uname -r)

        and look for a source line somewhere at debian.org. If there is one, then proceed to step (b). If you don't find one, then there's no prebuilt module for your kernel, so this installation method won't work for you; you should go ahead and try a different installation method.
     2. Find out if there are nvidia-glx and nvidia-kernel-common packages compatible with your nvidia-kernel-* package: run

        apt-cache policy nvidia-kernel-$(uname -r) nvidia-glx nvidia-kernel-common

        and look for versions of all three packages with compatible version numbers (identical up to the first - or +). If you find them, you're in luck; proceed to step (c).
        If you don't find compatible versions of all three nvidia-* packages, then you may still be able to find some on backports.org : search there for nvidia, add the lines it tells you about to your /etc/apt/sources.list, run apt-get update, and repeat this step.
        If after trying the above you still can't find compatible versions of the three nvidia-* packages, then sorry, but this installation method will not work for you. You should go another method. As a rule, nvidia-kernel-* packages are only available in the versions of the nvidia driver that were current at the same time as the kernels they were built for; while nvidia-glx is generally only available in the latest one or two versions. For example, at this writing nvidia-kernel-2.6.3-1-386 is only available in version 1.0.5336, while nvidia-glx is only available in version 1.0.7174. Those versions are incompatible, so if your kernel is a stock 2.6.3, then you have to either upgrade it or choose a different installation method for the nVidia drivers.
     3. If you found compatible nvidia-* packages in steps (a) and (b), then install them now:

        apt-get -t $NVDIST install nvidia-kernel-common nvidia-kernel-$(uname -r)

        (you'll install nvidia-glx below). You may have to adjust $NVDIST here, depending on where you found compatible versions of the nVidia packages in step (b), above. Sorry, but the possible permutations are too numerous to list here. 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 want or need to build your own nVidia kernel module or other add-on kernel modules.
     (The following procedure is adapted from the instructions in /usr/share/doc/nvidia-kernel-source/README.Debian.)
     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 -t $NVDIST 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: run

        apt-get -t $NVDIST 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. I won't try to document this step here; if you need to learn how, see the Kernel HOWTO and "How to Upgrade to the 2.6 Kernel" . But in summary, all 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 drivers:
        • Graphics Support –> nVidia Riva support (FB_RIVA)
        • Kernel Hacking –> Use 4Kb for kernel stacks instead of 8Kb (4KSTACKS)
        • Processor Type and Features –> Local APIC support on uniprocessors (X86_UP_APIC) (not available if you have an SMP kernel, including hyperthreading)
        I therefore recommend 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 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-image-*.deb and nvidia-kernel-*.deb, both in /usr/src. 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.
        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 following commands appropriately.
     4. Install the new kernel and kernel module:

        cd /usr/src
dpkg -i kernel-image-*.deb 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 that I rendered as * above.
2. Install the nVidia user-space libraries. Run

   apt-get -t $NVDIST install nvidia-glx

   If you're asked whether you want to install the thread-local storage libraries, say yes. Notes:
   • If the kernel you installed above is version 2.6.x, and the one you're running now is pre-2.6, then you should reboot with your new kernel before performing this step. The reason is that if you're not running a 2.6-series kernel when you perform this step, the thread-local storage part of the user-space libraries will not be installed. As a result your X server will crash when it tries to load the nVidia driver. If you already installed nvidia-glx earlier under a pre-2.6 kernel, then reboot to the new kernel, run dpkg-reconfigure nvidia-glx, and answer yes when asked if you want to install the TLS libraries.
   • 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 driver you've installed. This virtual package is provided by the kernel module package that you installed in step 1; so you have to complete that step first.
3. Update your configuration.
   1. Update /etc/X11/XF86Config-4. Naturally, there is both a Debian way and an old-fashioned way of doing this. Click on a method title to see the instructions.
       
      • The Debian way. This method avoids many common configuration errors, because you don't write an XF86Config-4 file yourself. Instead you answer a series of questions about your mouse, keyboard, and video hardware, and then the configuration script writes an XF86Config-4 file for you.
         
        1. Save yourself some possible grief later, by backing up your current XF86Config-4:

           cp -p /etc/X11/XF86Config-4 /etc/X11/XF86Config-4.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 .
        3. Run

           dpkg-reconfigure xserver-xfree86

           and answer all of the questions.
        4. When asked to choose an X server driver, choose "nvidia". An open-source alternative is the "nv" driver , which has 2D but no 3D capabilities.
        5. When asked to select X server modules, deselect (uncheck) GLCore and dri, and select (check) glx.
        When you're done, ls -l /etc/X11/XF86Config-4 to be sure your new XF86Config-4 file has been written. Thanks to Dave Page for informing me about this method.
      • The manual way. This method is simpler, and it 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:
        • 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.
        • 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 you want 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.

Notes

• Of course the nvidia module will have to be loaded into your kernel to work. If you've just installed the driver and don't need to reboot, then load the driver manually with modprobe nvidia or modconf before restarting your X server.
• 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.
• As I said above, you won't ever have to repeat steps 2 and 3 above, as long as you don't reverse them, of course.
• On the other hand, the kernel module that you built in step 1 is specific to the kernel you built it with. If you install a new kernel that's different in any way from the old one, you'll have to install a new driver module to go with it. In that case just go back and repeat step 1.
• Using this method, you don't need any of the following things:
  • The official nVidia installer from nvidia.com. The Debian packages contain all of the parts of it that you need.
  • Any of the patch or installer files available at minion.de . (But thanks to the folks at minion.de for providing those patches, during all of the time when the official nVidia drivers didn't work yet with kernel 2.6.)
  • The nvidia-kernel-src and nvidia-glx-src packages, which are deprecated. You can also ignore the nvidia-glx-dev package, unless you get complaints from some software (old games?) about missing libGL.so (thanks to Randall Donald for this information).
• You can ignore the warning at www.minion.de about carrying along the EXTRAVERSION information if you use --append-to-version with make-kpkg. Because you're using make-kpkg all the way through the build process, it takes care of this for you.
• If you have problems, see the Troubleshooting page .

Troubleshooting

Your kernel module won't build.

• If your kernel is version 2.6.5, you probably ran "make clean" after building the kernel. Starting in kernel 2.6.5, "make clean" has become more aggressive, so that it now removes some of the files you need in order to build your nvidia module (and apparently some other modules as well, including the ones in VMware). This is Debian bug #242038 . Note that "make clean" may run automatically after the kernel build, without you necessarily asking for it or noticing it. There are several possible solutions:
  • Run

    cd /usr/src/linux
make include/linux/version.h

    (thanks to Roberto Sanchez for this tip).
  • If you use "make-kpkg kernel_image" to build your kernel, you can prevent the "make clean" from running by adding a line

    do_clean := NO

    in /etc/kernel-pkg.conf. Now rerun "make-kpkg kernel_image".
  • Upgrade your kernel to a more recent version, and/or upgrade your kernel-package package to the testing or unstable version. The problem apparently has been fixed in more recent kernels, and also in later versions of kernel-package by setting do_clean:=NO by default.
  After any of the above steps, you should now be able to build your nvidia module.

You can build and install the drivers, but your X display won't function properly or at all after you reboot.

• If you first installed the nvidia-glx package while running kernel 2.4, the thread-local storage libraries in the package were not installed at that time. If you're now running kernel 2.6, then your driver will fail as a result, causing your X server to die with the opaque error message "Server caught signal 11". The solution is to run 'dpkg-reconfigure nvidia-glx' while running kernel 2.6. (Thanks to Alberto Guzmán for this tip.)
• If you've just upgraded to kernel 2.6, make sure you've installed the module-init-tools package, which replaces the old modutils package, for loading kernel modules. If you don't do this, none of your kernel modules will load, including nvidia, so (among other problems) your X display won't start. For this and other information, you really must read "How to Upgrade to the 2.6 Kernel" .
• 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/nvidia*:
  $ ls -l /dev/nvidia* crw-rw---- 1 root video 195, 0 Nov 10 03:59 /dev/nvidia0 crw-rw---- 1 root video 195, 1 Nov 10 03:59 /dev/nvidia1 crw-rw---- 1 root video 195, 2 Nov 10 03:59 /dev/nvidia2 crw-rw---- 1 root video 195, 3 Nov 10 03:59 /dev/nvidia3 crw-rw---- 1 root video 195, 4 Nov 10 03:59 /dev/nvidia4 crw-rw---- 1 root video 195, 5 Nov 10 03:59 /dev/nvidia5 crw-rw---- 1 root video 195, 6 Nov 10 03:59 /dev/nvidia6 crw-rw---- 1 root video 195, 7 Nov 10 03:59 /dev/nvidia7 crw-rw---- 1 root video 195, 255 Nov 10 03:59 /dev/nvidiactl
  If you don't have them, it's probably because you're running udev or devfs. In any case, the simplest way to fix this problem is to upgrade to a recent version of the nvidia-kernel-common package, which includes a boot script (/etc/init.d/nvidia-kernel) that recreates these devices after every reboot. The boot script is present in version 20051028+1, at least, of nvidia-kernel-common. Once you've upgraded nvidia-kernel-common, you can either reboot or just run /etc/init.d/nvidia-kernel start to create the device files.
• Since kernel 2.6.5-mm?, there is a kernel option called 4KSTACKS which is incompatible with the nVidia driver, and will cause it to crash. Turn it off:
  • If your kernel is version 2.6.5-mm?, 4KSTACKS isn't part of the regular kernel .config file; to turn it off you have to edit /usr/src/linux/arch/i386/Kconfig, find "config 4KSTACKS", and change the "def_bool y" that follows to "def_bool n". (Thanks to Antti Kumar for this description.)
  • In kernel 2.6.6 or later, CONFIG_4KSTACKS is a regular kernel option, which you can find in the kernel config under Kernel hacking –> Use 4Kb for kernel stacks.
  Then rebuild your kernel and nvidia module. Note: I have no experience with this. I'm just passing along what many people have reported either in the newsgroups or directly to me. Has this problem been fixed in the latest nVidia drivers?
• Kernel 2.6.9 has some particular problems with nVidia drivers:
  • If loading your nvidia kernel module fails with an error message "Unknown symbol VMALLOC_RESERVE", then you need to apply this patch to your kernel source. Download and save the patch into /usr/src, then run

    cd /usr/src/linux
patch -p1 < ../nvidia-vmalloc-reserve.patch

    Then rebuild and reinstall your kernel and nVidia driver, and try again. I've been told that this problem only occurs with nVidia driver version 1.0.6111.
  • Many people have reported ( 1 , 2 , 3 ) that the combination of a Riva TNT2 video card with kernel 2.6.9 and nVidia driver 1.0.6629 gives them a black screen, or a screen with garbage. The workaround is to go back to driver 1.0.6111. There's reason to believe that this problem has been fixed in the driver development code, so it should be fixed in the next release. Thanks to Hugo Vanvoerkom for reporting this problem.
• Kernel 2.6.10 apparently also has some particular problems with nVidia drivers versions 1.0.6111 and 1.0.6629:
  • You will need to apply the VMALLOC_RESERVE patch .
  • If loading your nvidia kernel module fails with an error message "Unknown symbol pci_find-class", then you need to apply this patch to your kernel source. Download and save the patch into /usr/src, then run

    cd /usr/src/linux
patch -p1 < ../nvidia-pci-find-class.patch

  • Some people have reported "kernel oopses" or black screens that were solved by this patch . Download and save it into /usr/src, then run

    cd /usr/src/modules/nvidia-kernel/nv
patch -p3 < /usr/src/nvidia-kernel-2.6.10.patch

  After applying these patches, rebuild and reinstall your kernel and nVidia driver and try again. Thanks to Stéphane Huc for reporting these issues to me.
• The rivafb kernel module is known to be incompatible with the nVidia driver; see /usr/share/doc/nvidia-kernel-source/README.Debian . To see if you have this module inserted in your kernel, run 'lsmod | grep rivafb' . If you do, then get rid of it by, in increasing order of forcefulness: 'rmmod rivafb'; 'rm /lib/modules/`uname -r`/kernel/drivers/video/riva/rivafb.ko'; or disabling the module in your kernel config (Device drivers –> Graphics support –> nVidia Riva) and rebuilding your kernel. (If you still want a framebuffer driver, try VESA VGA; it's slow but works well.)
• Newer kernels (≥2.6.12 or so) also have an nVidia framebuffer option (FB_NVIDIA; nvidiafb module). I haven't tried this, but the same advice applies as with rivafb: don't use it. It will probably conflict with the nVidia non-free driver. If you want framebuffer support, use VESA VGA instead.
• Several users have reported to me that they had hard lockups when switching virtual terminals or shutting down their X servers, until they recompiled their kernels with local APIC disabled. 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. :(
• One user reports that his screen stayed black until he loaded the "unix" kernel module, since his X server couldn't connect to Unix-domain sockets.
• One user reports that his X server wouldn't start until he removed the Chipset option from the Device section for his video card in /etc/X11/XF86Config-4.
• One user reports that he had hard lockups every time X started, until he found and removed the file /usr/X11R6/lib/modules/drivers/nvidia_drv.so.
• Look in /var/log/XFree86.0.log. 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.
• Try switching to the nv driver: go back and repeat step 3a , but this time select driver "nv" instead of "nvidia". Then restart your X server. If it still won't start, then you have other problems that precede the nVidia driver. (Try apt-get install x-window-system-core to make sure you have a minimal functioning X setup.)
• Read the README files that I mention at the end of the Installation section. They have a lot of useful information about the driver.
• The Debian X Window System FAQ lists solutions to many common problems in getting your X server to work with your hardware.
• You can try searching or posting to the nVidia-Linux forum at nvnews.net.

Hardware acceleration, aka direct rendering, doesn't work.

You can detect this by running

glxinfo | grep "direct rendering"

If the answer is No, then you're using software acceleration for 3D. That means that your CPU is doing the work that your GPU should be doing, so with any recent video hardware, you're getting poorer frame rates and higher CPU utilization than your hardware permits. To correct this:

• Be sure that you've installed the nvidia-glx package.
• Be sure that you've adjusted your X server configuration, as I describe on the installation page .
• You may be using different client and server versions of GLX, due to incorrectly installed symlinks. This is Debian bug #208198 . Run

  glxinfo | egrep "glx (vendor|version)"

  and if you see different vendors or versions for the client and server, this is your problem. In that case run

   

  ln -fs /usr/lib/libGL.so.$NVVER /usr/X11R6/lib/libGL.so ln -fs /usr/lib/libGL.so.$NVVER /usr/X11R6/lib/libGL.so.1 ln -fs libGL.so.$NVVER /usr/lib/libGL.so.1.2

  where $NVVER is the version of your nvidia-glx package, e.g. 1.0.7174 as of this writing in stable, testing, and unstable.

After taking any of the above steps you'll have to restart your X server to get hardware acceleration working. But before you do that, run glxgears for a while and take note of the frame rates. Then check them again after you restart with hardware acceleration—my frame rates jumped from 570 to 3750/s.

You get a warning message on your console or in your syslog, saying "nvidia license taints kernel".

• Don't worry. Your kernel is fine. 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 LKML FAQ for more.

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.

This document explains how to build and install drivers for nVidia video hardware under Debian GNU/Linux, or any of its derivatives including Libranet, Mepis, Ubuntu, or Xandros. The method works with any 2.4- or 2.6-series Linux kernel, and with either stock or custom kernels.

To install the nVidia drivers, you can use either an official installer from nVidia, or the Debian driver packages. Each method has its advantages, as I describe below . The official installer used to be easier to use; but with the advent of module-assistant , they're about equally easy, or the Debian way may even be 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 official installer is pretty self-explanatory, 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.

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.

The Debian Way vs. the nVidia Installer

The method that I describe here is "the Debian way": you build package files (*.deb) for your kernel and driver, and then install them as usual using dpkg or apt-get. This method has some advantages, compared to using the official nVidia installer:

• 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 nVidia packages and package management tools, so it's cleaner and makes use of what you already know about these tools.
• 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 (although that's a pretty short lag for Debian packages). (Compare the nVidia and Debian unstable version numbers to see how much difference there is today.)
• 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 I wrote this HOWTO :)
• You won't have to learn about module-assistant, or make-kpkg. Wait, is this an advantage?
• People have occasionally reported to me 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.

For me, the Debian way works best with this driver. Use the method that works best for you. 

Installation

Here are the instructions for building and installing your nVidia 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 user libraries and kernel module source only have to be installed once. Then the kernel module has to be rebuilt every time you rebuild or change your kernel. So, here's what you will do:

1. Build and install the kernel module.
2. Install the user-space libraries.
3. Update your configuration.

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

Steps 2 and 3 have to be performed only once. Step 1 you have to repeat 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.

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 don't know what kind of kernel you're running, then it's probably a stock kernel. But to find out, run

apt-cache policy kernel-image-$(uname -r)

and look at the source lines for the version that's listed as installed. If the source lines include something at debian.org, then you're running a stock kernel. If no version is listed as installed, then you're running a custom kernel. If a version is installed, but the only source listed for the installed version is /var/lib/dpkg/status, then you may be running a custom kernel, or a stock kernel that's old enough to have dropped out of the Debian distribution. The easiest way to tell is just to look at the kernel version number (output of uname -r): if it looks like e.g. 2.4.x-1-k7 or 2.6.x-1-686, then it's probably an old stock kernel.

Choose a Distribution

Before you install the Debian nVidia packages, you should choose a distribution, either 'testing' or 'unstable', from which to install them. There is no 'stable' version of these packages at present. You can run 'apt-cache policy nvidia-kernel-source' to see which versions of the driver are available in each distribution.

Once you've chosen a distribution, put its value into a shell variable NVDIST, by executing one of the following lines:

NVDIST=testing
NVDIST=unstable

I will use $NVDIST to represent this value in all of the commands below. Also, make sure that your /etc/apt/sources.list contains a line like 'deb http://http.us.debian.org/debian $NVDIST main contrib non-free', for your $NVDIST. (Help yourself to a copy of my sources.list if you like.) And if you've just modified /etc/apt/sources.list, you need to run 'apt-get update' before continuing below.

Installation Instructions

1. Build and install the kernel module.
   There are four different procedures that you can use to install the kernel module. If that sounds like a lot, don't worry—I've listed the easiest methods first. So start with the first one, and if it doesn't work for you, go on down the list. Click on the title of each method to see the instructions.
   • 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:

     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 .
     module-assistant automates the more detailed procedures described below: it downloads the nvidia kernel module source, builds a kernel module package compatible with your (stock or custom) kernel, and installs the package. (If you're interested, the package file is /usr/src/nvidia-kernel-*.deb, and you can see that it's installed by running apt-cache policy nvidia-kernel-$(uname -r).) Of course module-assistant has many other operations and options; see the man page for details.
     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. (Thanks to Josep Ma Antolin for this tip.)
   • Install a pre-built module. This method is easy if you're running a recent stock kernel ; will take a little more work and may fail if you're running an older stock kernel; and will not work at all if you're running a custom kernel .
      
     1. Find out if there's a prebuilt module available for your kernel. The official Debian mirrors include prebuilt modules for just a few stock kernels, but Randall Donald maintains unofficial prebuilt modules for many other old and current stock kernels. To get access to Randall's repository, add

        deb http://people.debian.org/~rdonald/nvidia modules-unstable/i386/

        into your /etc/apt/sources.list. Now run

        apt-get update
apt-cache policy nvidia-kernel-$(uname -r)

        and look for a source line somewhere at debian.org. If there is one, then proceed to step (b). If you don't find one, then there's no prebuilt module for your kernel, so this installation method won't work for you; you should go ahead and try a different installation method.
     2. Find out if there are nvidia-glx and nvidia-kernel-common packages compatible with your nvidia-kernel-* package: run

        apt-cache policy nvidia-kernel-$(uname -r) nvidia-glx nvidia-kernel-common

        and look for versions of all three packages with compatible version numbers (identical up to the first - or +). If you find them, you're in luck; proceed to step (c).
        If you don't find compatible versions of all three nvidia-* packages, then you may still be able to find some on backports.org : search there for nvidia, add the lines it tells you about to your /etc/apt/sources.list, run apt-get update, and repeat this step.
        If after trying the above you still can't find compatible versions of the three nvidia-* packages, then sorry, but this installation method will not work for you. You should go another method. As a rule, nvidia-kernel-* packages are only available in the versions of the nvidia driver that were current at the same time as the kernels they were built for; while nvidia-glx is generally only available in the latest one or two versions. For example, at this writing nvidia-kernel-2.6.3-1-386 is only available in version 1.0.5336, while nvidia-glx is only available in version 1.0.7174. Those versions are incompatible, so if your kernel is a stock 2.6.3, then you have to either upgrade it or choose a different installation method for the nVidia drivers.
     3. If you found compatible nvidia-* packages in steps (a) and (b), then install them now:

        apt-get -t $NVDIST install nvidia-kernel-common nvidia-kernel-$(uname -r)

        (you'll install nvidia-glx below). You may have to adjust $NVDIST here, depending on where you found compatible versions of the nVidia packages in step (b), above. Sorry, but the possible permutations are too numerous to list here. 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 want or need to build your own nVidia kernel module or other add-on kernel modules.
     (The following procedure is adapted from the instructions in /usr/share/doc/nvidia-kernel-source/README.Debian.)
     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 -t $NVDIST 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: run

        apt-get -t $NVDIST 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. I won't try to document this step here; if you need to learn how, see the Kernel HOWTO and "How to Upgrade to the 2.6 Kernel" . But in summary, all 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 drivers:
        • Graphics Support –> nVidia Riva support (FB_RIVA)
        • Kernel Hacking –> Use 4Kb for kernel stacks instead of 8Kb (4KSTACKS)
        • Processor Type and Features –> Local APIC support on uniprocessors (X86_UP_APIC) (not available if you have an SMP kernel, including hyperthreading)
        I therefore recommend 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 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-image-*.deb and nvidia-kernel-*.deb, both in /usr/src. 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.
        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 following commands appropriately.
     4. Install the new kernel and kernel module:

        cd /usr/src
dpkg -i kernel-image-*.deb 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 that I rendered as * above.
2. Install the nVidia user-space libraries. Run

   apt-get -t $NVDIST install nvidia-glx

   If you're asked whether you want to install the thread-local storage libraries, say yes. Notes:
   • If the kernel you installed above is version 2.6.x, and the one you're running now is pre-2.6, then you should reboot with your new kernel before performing this step. The reason is that if you're not running a 2.6-series kernel when you perform this step, the thread-local storage part of the user-space libraries will not be installed. As a result your X server will crash when it tries to load the nVidia driver. If you already installed nvidia-glx earlier under a pre-2.6 kernel, then reboot to the new kernel, run dpkg-reconfigure nvidia-glx, and answer yes when asked if you want to install the TLS libraries.
   • 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 driver you've installed. This virtual package is provided by the kernel module package that you installed in step 1; so you have to complete that step first.
3. Update your configuration.
   1. Update /etc/X11/XF86Config-4. Naturally, there is both a Debian way and an old-fashioned way of doing this. Click on a method title to see the instructions.
       
      • The Debian way. This method avoids many common configuration errors, because you don't write an XF86Config-4 file yourself. Instead you answer a series of questions about your mouse, keyboard, and video hardware, and then the configuration script writes an XF86Config-4 file for you.
         
        1. Save yourself some possible grief later, by backing up your current XF86Config-4:

           cp -p /etc/X11/XF86Config-4 /etc/X11/XF86Config-4.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 .
        3. Run

           dpkg-reconfigure xserver-xfree86

           and answer all of the questions.
        4. When asked to choose an X server driver, choose "nvidia". An open-source alternative is the "nv" driver , which has 2D but no 3D capabilities.
        5. When asked to select X server modules, deselect (uncheck) GLCore and dri, and select (check) glx.
        When you're done, ls -l /etc/X11/XF86Config-4 to be sure your new XF86Config-4 file has been written. Thanks to Dave Page for informing me about this method.
      • The manual way. This method is simpler, and it 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:
        • 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.
        • 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 you want 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.

Notes

• Of course the nvidia module will have to be loaded into your kernel to work. If you've just installed the driver and don't need to reboot, then load the driver manually with modprobe nvidia or modconf before restarting your X server.
• 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.
• As I said above, you won't ever have to repeat steps 2 and 3 above, as long as you don't reverse them, of course.
• On the other hand, the kernel module that you built in step 1 is specific to the kernel you built it with. If you install a new kernel that's different in any way from the old one, you'll have to install a new driver module to go with it. In that case just go back and repeat step 1.
• Using this method, you don't need any of the following things:
  • The official nVidia installer from nvidia.com. The Debian packages contain all of the parts of it that you need.
  • Any of the patch or installer files available at minion.de . (But thanks to the folks at minion.de for providing those patches, during all of the time when the official nVidia drivers didn't work yet with kernel 2.6.)
  • The nvidia-kernel-src and nvidia-glx-src packages, which are deprecated. You can also ignore the nvidia-glx-dev package, unless you get complaints from some software (old games?) about missing libGL.so (thanks to Randall Donald for this information).
• You can ignore the warning at www.minion.de about carrying along the EXTRAVERSION information if you use --append-to-version with make-kpkg. Because you're using make-kpkg all the way through the build process, it takes care of this for you.
• If you have problems, see the Troubleshooting page .

Troubleshooting

Your kernel module won't build.

• If your kernel is version 2.6.5, you probably ran "make clean" after building the kernel. Starting in kernel 2.6.5, "make clean" has become more aggressive, so that it now removes some of the files you need in order to build your nvidia module (and apparently some other modules as well, including the ones in VMware). This is Debian bug #242038 . Note that "make clean" may run automatically after the kernel build, without you necessarily asking for it or noticing it. There are several possible solutions:
  • Run

    cd /usr/src/linux
make include/linux/version.h

    (thanks to Roberto Sanchez for this tip).
  • If you use "make-kpkg kernel_image" to build your kernel, you can prevent the "make clean" from running by adding a line

    do_clean := NO

    in /etc/kernel-pkg.conf. Now rerun "make-kpkg kernel_image".
  • Upgrade your kernel to a more recent version, and/or upgrade your kernel-package package to the testing or unstable version. The problem apparently has been fixed in more recent kernels, and also in later versions of kernel-package by setting do_clean:=NO by default.
  After any of the above steps, you should now be able to build your nvidia module.

You can build and install the drivers, but your X display won't function properly or at all after you reboot.

• If you first installed the nvidia-glx package while running kernel 2.4, the thread-local storage libraries in the package were not installed at that time. If you're now running kernel 2.6, then your driver will fail as a result, causing your X server to die with the opaque error message "Server caught signal 11". The solution is to run 'dpkg-reconfigure nvidia-glx' while running kernel 2.6. (Thanks to Alberto Guzmán for this tip.)
• If you've just upgraded to kernel 2.6, make sure you've installed the module-init-tools package, which replaces the old modutils package, for loading kernel modules. If you don't do this, none of your kernel modules will load, including nvidia, so (among other problems) your X display won't start. For this and other information, you really must read "How to Upgrade to the 2.6 Kernel" .
• 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/nvidia*:
  $ ls -l /dev/nvidia* crw-rw---- 1 root video 195, 0 Nov 10 03:59 /dev/nvidia0 crw-rw---- 1 root video 195, 1 Nov 10 03:59 /dev/nvidia1 crw-rw---- 1 root video 195, 2 Nov 10 03:59 /dev/nvidia2 crw-rw---- 1 root video 195, 3 Nov 10 03:59 /dev/nvidia3 crw-rw---- 1 root video 195, 4 Nov 10 03:59 /dev/nvidia4 crw-rw---- 1 root video 195, 5 Nov 10 03:59 /dev/nvidia5 crw-rw---- 1 root video 195, 6 Nov 10 03:59 /dev/nvidia6 crw-rw---- 1 root video 195, 7 Nov 10 03:59 /dev/nvidia7 crw-rw---- 1 root video 195, 255 Nov 10 03:59 /dev/nvidiactl
  If you don't have them, it's probably because you're running udev or devfs. In any case, the simplest way to fix this problem is to upgrade to a recent version of the nvidia-kernel-common package, which includes a boot script (/etc/init.d/nvidia-kernel) that recreates these devices after every reboot. The boot script is present in version 20051028+1, at least, of nvidia-kernel-common. Once you've upgraded nvidia-kernel-common, you can either reboot or just run /etc/init.d/nvidia-kernel start to create the device files.
• Since kernel 2.6.5-mm?, there is a kernel option called 4KSTACKS which is incompatible with the nVidia driver, and will cause it to crash. Turn it off:
  • If your kernel is version 2.6.5-mm?, 4KSTACKS isn't part of the regular kernel .config file; to turn it off you have to edit /usr/src/linux/arch/i386/Kconfig, find "config 4KSTACKS", and change the "def_bool y" that follows to "def_bool n". (Thanks to Antti Kumar for this description.)
  • In kernel 2.6.6 or later, CONFIG_4KSTACKS is a regular kernel option, which you can find in the kernel config under Kernel hacking –> Use 4Kb for kernel stacks.
  Then rebuild your kernel and nvidia module. Note: I have no experience with this. I'm just passing along what many people have reported either in the newsgroups or directly to me. Has this problem been fixed in the latest nVidia drivers?
• Kernel 2.6.9 has some particular problems with nVidia drivers:
  • If loading your nvidia kernel module fails with an error message "Unknown symbol VMALLOC_RESERVE", then you need to apply this patch to your kernel source. Download and save the patch into /usr/src, then run

    cd /usr/src/linux
patch -p1 < ../nvidia-vmalloc-reserve.patch

    Then rebuild and reinstall your kernel and nVidia driver, and try again. I've been told that this problem only occurs with nVidia driver version 1.0.6111.
  • Many people have reported ( 1 , 2 , 3 ) that the combination of a Riva TNT2 video card with kernel 2.6.9 and nVidia driver 1.0.6629 gives them a black screen, or a screen with garbage. The workaround is to go back to driver 1.0.6111. There's reason to believe that this problem has been fixed in the driver development code, so it should be fixed in the next release. Thanks to Hugo Vanvoerkom for reporting this problem.
• Kernel 2.6.10 apparently also has some particular problems with nVidia drivers versions 1.0.6111 and 1.0.6629:
  • You will need to apply the VMALLOC_RESERVE patch .
  • If loading your nvidia kernel module fails with an error message "Unknown symbol pci_find-class", then you need to apply this patch to your kernel source. Download and save the patch into /usr/src, then run

    cd /usr/src/linux
patch -p1 < ../nvidia-pci-find-class.patch

  • Some people have reported "kernel oopses" or black screens that were solved by this patch . Download and save it into /usr/src, then run

    cd /usr/src/modules/nvidia-kernel/nv
patch -p3 < /usr/src/nvidia-kernel-2.6.10.patch

  After applying these patches, rebuild and reinstall your kernel and nVidia driver and try again. Thanks to Stéphane Huc for reporting these issues to me.
• The rivafb kernel module is known to be incompatible with the nVidia driver; see /usr/share/doc/nvidia-kernel-source/README.Debian . To see if you have this module inserted in your kernel, run 'lsmod | grep rivafb' . If you do, then get rid of it by, in increasing order of forcefulness: 'rmmod rivafb'; 'rm /lib/modules/`uname -r`/kernel/drivers/video/riva/rivafb.ko'; or disabling the module in your kernel config (Device drivers –> Graphics support –> nVidia Riva) and rebuilding your kernel. (If you still want a framebuffer driver, try VESA VGA; it's slow but works well.)
• Newer kernels (≥2.6.12 or so) also have an nVidia framebuffer option (FB_NVIDIA; nvidiafb module). I haven't tried this, but the same advice applies as with rivafb: don't use it. It will probably conflict with the nVidia non-free driver. If you want framebuffer support, use VESA VGA instead.
• Several users have reported to me that they had hard lockups when switching virtual terminals or shutting down their X servers, until they recompiled their kernels with local APIC disabled. 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. :(
• One user reports that his screen stayed black until he loaded the "unix" kernel module, since his X server couldn't connect to Unix-domain sockets.
• One user reports that his X server wouldn't start until he removed the Chipset option from the Device section for his video card in /etc/X11/XF86Config-4.
• One user reports that he had hard lockups every time X started, until he found and removed the file /usr/X11R6/lib/modules/drivers/nvidia_drv.so.
• Look in /var/log/XFree86.0.log. 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.
• Try switching to the nv driver: go back and repeat step 3a , but this time select driver "nv" instead of "nvidia". Then restart your X server. If it still won't start, then you have other problems that precede the nVidia driver. (Try apt-get install x-window-system-core to make sure you have a minimal functioning X setup.)
• Read the README files that I mention at the end of the Installation section. They have a lot of useful information about the driver.
• The Debian X Window System FAQ lists solutions to many common problems in getting your X server to work with your hardware.
• You can try searching or posting to the nVidia-Linux forum at nvnews.net.

Hardware acceleration, aka direct rendering, doesn't work.

You can detect this by running

glxinfo | grep "direct rendering"

If the answer is No, then you're using software acceleration for 3D. That means that your CPU is doing the work that your GPU should be doing, so with any recent video hardware, you're getting poorer frame rates and higher CPU utilization than your hardware permits. To correct this:

• Be sure that you've installed the nvidia-glx package.
• Be sure that you've adjusted your X server configuration, as I describe on the installation page .
• You may be using different client and server versions of GLX, due to incorrectly installed symlinks. This is Debian bug #208198 . Run

  glxinfo | egrep "glx (vendor|version)"

  and if you see different vendors or versions for the client and server, this is your problem. In that case run

   

  ln -fs /usr/lib/libGL.so.$NVVER /usr/X11R6/lib/libGL.so ln -fs /usr/lib/libGL.so.$NVVER /usr/X11R6/lib/libGL.so.1 ln -fs libGL.so.$NVVER /usr/lib/libGL.so.1.2

  where $NVVER is the version of your nvidia-glx package, e.g. 1.0.7174 as of this writing in stable, testing, and unstable.

After taking any of the above steps you'll have to restart your X server to get hardware acceleration working. But before you do that, run glxgears for a while and take note of the frame rates. Then check them again after you restart with hardware acceleration—my frame rates jumped from 570 to 3750/s.

You get a warning message on your console or in your syslog, saying "nvidia license taints kernel".

• Don't worry. Your kernel is fine. 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 LKML FAQ for more.

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.