Building the nvidia-kernel debian package

Carlo Wood, December 2006 (last updated 19 Aug 2008)


The scripts don't work anymore. On debian testing you are now advised to use this method:

apt-get install module-assistant nvidia-kernel-source
m-a prepare
m-a clean nvidia
m-a a-i nvidia
apt-get install nvidia-glx
depmod -a
modprobe nvidia
# This is only necessary if you start to use nvidia for the first time:
dpkg-reconfigure xserver-xorg



Nvidia is still the best video card to use for Dual-Head on GNU/Linux. The reason for this is their support for linux with proprietary drivers, unlike for example Matrox or ATI. Matrox made some video card drivers open source in the past but at the moment of writing (December 2006) their support of the Open Source community has hit rock bottom. This is a huge problem for Dual-Head cards since no open source code to properly initialize them is available: there is simply no support for acceleration and Dual-Head on linux when using Matrox or (the newer) ATI cards.

There are several methods to obtain Dual-Head on linux:

However, only the first one can be taken seriously as the other three have a serious lack of acceleration support.

Using Xinerama there is no DRI possible and in the case of Matrox (I never really tried ATI, but I heard that is at least as badly supported) there is no acceleration on the second head (no openGL and no video can be used on it) and while playing a DVD might work on the first head, openGL applications are extremely slow.

I read that Merged Frame Buffer supposedly supports acceleration, but my experience is different. It is unusable nevertheless because this method results in two monitors appearing as one screen: the window manager has no notion of two monitors existing at all and centralized applications appear on the edge of the two monitors. Also (horizontally) maximized windows span both monitors making maximization unusable.

Using the traditional support of two monitors as two different X displays is unusable too: it is impossible to move a window from one monitor to another (you have to duplicate all panel buttons to have them open an application on one or the other monitor) and when, for example, firefox is already running on one display, trying to open an url on the other fails because firefox detects that it is already running but cannot connect to the running instance (due to a mismatch of the window id). Moreover, also in this case you still don't have acceleration on the second head when using a dual-head Matrox card. Now I don't say that this is impossible, because Matrox still released a closed source plugin for X that should be able to initialize the second head correctly (mga_hal) - but the developers of xorg decided to remove the support for mga_hal from Xorg-7.x. They plan to replace the functionality with open source code in the future (is my understanding), or something. Sometimes open source developers are no better than a black box: I have no feedback on why they did this, what are their plans and if this is ever going to work again.

Finally, using the first option gives you the best of everything: Full 'native' support of all acceleration on both heads, even for the latest video cards; and full awareness of being Dual-Head (I had to patch my window manager (metacity) to improve the actual dual-head support; but it is basically all there).

Unfortunately, there are also disadvantages to this method. For one thing, the drivers are closed source: if something doesn't work you're basically screwed. That is, there are a lot of wizard-level xorg.conf Options specific to Nvidia's drivers to help to work around problems in most cases, but it asks a great deal of persistence from your part (and a lot of reading online, like you are doing now).

Another disadvantage of Nvidia's drivers is the fact that they need to install shared graphics libraries, replacing the ones that are part of your normal Operating System. While theoretically this shouldn't have to be a problem, in practise it can lead to an unstable Operating System with unmatching versions that cause instability (of the X Windowing System), of openGL, or - in most cases - make it impossible to start X at all or only on one monitor. Recovering from such broken systems means basically a complete re-install of the Operating System; but you won't know that it is broken; you will be thinking it is something else (configuration, bugs in the drivers, X or both, an incompatible kernel version or even suspect hardware problems).

The main reason for these dramatic problems is interference with the native package manager of your distribution. In order to avoid such problem on debian you should therefore never use Nvidia's installer, but instead use the packages provided by debian. These install the same drivers, but keep track of which libraries are replaced (in fact, they use a system with symbolic links that are updated) and this method does not interfere with normal upgrades (running apt-get).

Now you might ask yourself: then why the need for this HOWTO? Three reasons:

  1. The debian maintainers regulary REMOVE the nvidia kernel module package from debian 'testing'. I was told this was because it was broken but I never saw any prove of that, and even so, why not just fix it?
  2. If you are using debian testing, and even if you are using debian unstable, the version of the used nvidia drivers lags a bit with the latest driver releases by nvidia. If for some reason you need the latest (beta) releases from nvidia then you will also need this HOWTO to build your own debian packages. Such reasons can be: a bug fix in the drivers needed for your specific card, or-- you need to use the latest drivers for a yet unknown problem with your setup in order to get support from Nvidia.
  3. If you are using a custom kernel, or an older kernel than is currently in debian testing/unstable, then there won't be debian packages that support your kernel (anymore).


In this HOWTO it is assumed that you are using debian testing, simply because that is what I am using. If you are not then things might be different for you here and there.

Before you start-- update your system completely by running the usual commands:

$ sudo apt-get update
$ sudo apt-get upgrade

If this leads to any packages being 'kept back', then either use apt-get dist-upgrade or run apt-get install kept-back-package afterwards, as usual.

In order to address the problem that nvidia-kernel is no longer in debian testing (lenny), we will need to get packages and source code from debian unstable Therefore, edit your /etc/apt/sources.list and add deb and deb-src lines for unstable. You can achieve this by duplicating the lines that you have for testing and then replace testing with unstable. Also, make sure that you have non-free listed as section. The result should look something like this:

deb http://your.favourite.mirror/pub/os/Linux/distr/debian/ testing main contrib non-free
deb http://your.favourite.mirror/pub/os/Linux/distr/debian/ unstable main contrib non-free
deb-src http://your.favourite.mirror/pub/os/Linux/distr/debian/ testing main contrib non-free
deb-src http://your.favourite.mirror/pub/os/Linux/distr/debian/ unstable main contrib non-free

Do not run apt-get (dist-)upgrade at this point, as it would upgrade your whole system to unstable: you don't want that. First, you have to tell your system to use testing by default......... If you do NOT have a /etc/apt/preferences file then you could achieve this by adding the following line to your /etc/apt/apt.conf file:

APT::Default-Release "testing";

But if you are using pinning, then you can't do that. Instead add a pin for testing as is described here. Note that I have written a Pinning Errata (corrections on existing, or missing documentation on Pinning) that should help to understand pinning better (after reading other documentation).

Now run

$ sudo apt-get update

again to get the package lists of unstable. Then you might run sudo apt-get upgrade to verify that it will indeed not upgrade anything (but stick to testing) ;). You can also test it by running apt-cache policy libc6 which should print something like:

  Installed: 2.7-10
  Candidate: 2.7-10
  Version table:
     2.7-12 0
        500 unstable/main Packages
 *** 2.7-10 0
        990 testing/main Packages
        100 /var/lib/dpkg/status

Note the 990 priority for testing, while unstable is 500.

With that out of the way, we can start to do some real work.

Basic sid backporting

The following method actually checks if nvidia-kernel was added back to testing, in which case you didn't even have to do the above. However, if the package still wasn't added back then you will get the version from unstable. You can also use this method to get unstable anyway: I explicitely tell apt-get to use unstable below, whenever that is required.

There are still packages in testing that we can use regardless. Lets do that first (if you don't already have them installed). Run the following command:

$ sudo apt-get install nvidia-kernel-common

This should succeed or something is wrong.

Next, we try what would happen if we'd try to install/upgrade nvidia-glx at this point by running:

$ sudo apt-get install --dry-run nvidia-glx

If this prints that it would drag in a kernel image from unstable, like this:

Inst linux-image-2.6.18-3-k7 (2.6.18-6 Debian:unstable)

note the strings Inst linux-image and Debian:unstable then this means that not all needed packages could be found in testing. Another error you might see is:

nvidia-glx: Depends: nvidia-kernel-169.12 but it is not going to be installed

Both are most likely because nvidia-kernel is still missing (this is the only package that is missing at the time of writing this) and we need to build it ourselves. The latter error happens when the nvidia-kernel in unstable depends on versions (like the kernel) in unstable that are simply not available in testing.

If nvidia-kernel is back in testing, then you can just run the above command again without --dry-run and you are done.

Otherwise, to build nvidia-kernel, download the automagic script build-nvidia-kernel and run it. You don't need to run it as root: it uses sudo for those commands that need to be run as root (apt-get and dpkg.)

The script will populate the current directory with quite some files (and directories), so you might want to put it in an empty directory before running it (I have it in /usr/src/nvidia.) You need write access to that directory.

The script is pretty intelligent and should catch most problems either giving useful hints or fixing the problem. You must be running a 2.6 kernel version however.

$ ./build-nvidia-kernel

If all goes well then this will create the debian packages that are needed in a directory named after the kernel version. If it fails, then do what is described under Using the drivers from below.

In order to install it, run the script ./install-nvidia-debian.

$ ./install-nvidia-debian --version=169.?? --kernel=`uname -r`

Where 169.?? (or 100.??.?? (or 1.0.????) for older versions) is the version of the nvidia drivers that you want to install (the ones that you just compiled thus). Note that install-nvidia-debian doesn't really install anything, it just figures out which commands you should run as root and prints those commands to standard out. However, if you are using a local repository as is described here, then it automatically updates the repository (by updating the symbolic links from the repository to the just created .deb files.

This might remove some mesa related packages. That is correct as it will replace those.

If at any later time you upgraded your kernel version, most likely stopping X from starting, than you just need to rerun ./build-nvidia-kernel and ./install-nvidia-debian and you should be ready to go.

Using the drivers from

If the version of the NVIDIA driver in debian unstable is not new enough for you (or when you want older versions!), then read the following that will describe how to replace the drivers with drivers as released by Nvidia.

The lastest (beta) drivers from Nvidia can be downloaded here Older drivers can be downloaded from nvidia's ftp site: Linux 32-bit and Linux 64-bit. In either case, if you have Linux 64-bit, you will ALSO need to download the Linux 32-bit drivers because those will be needed to build nvidia-glx-ia32.

Download the (two) NVIDIA-Linux-x86*-* file(s) and put them in the same directory as the build-nvidia-kernel script. Note that the package suffix ('-pkg#') is used to distinguish between packages containing the same driver, but with different precompiled kernel interfaces. We don't use precompiled kernel modules, so just download pkg0 (the smallest one). Then run:

./build-nvidia-kernel --runfile=1.0-????
./build-nvidia-kernel --runfile=100.??.??
./build-nvidia-kernel --runfile=169.??

Replace ?? with the correct patch level, of course.

Warning: when using --runfile, the script builds the new debian packages using the latest official version in the current directory as template. It does this by simply replacing the version numbers. This means that theoretically the resulting packages can be broken. You should probably first look at the contents of the resulting packages (with dpkg --contents *.deb) and compare that with older (good) packages before installing them. Also, make sure that you have the older packages ready to reinstall them, downgrading to versions you know to work. I tested it with release 1.0-7667 up till and including 1.0-9755, 100.14.03, 100.14.11, 100.14.19 and 169.12. Use at own risk.

Finally, make sure to rmmod and modprobe the nvidia driver before starting X again! For example,

sudo rmmod nvidia
sudo modprobe nvidia  # Check if correct version is loaded
startx -- -logverbose 5


The mentioned scripts. Read the above to learn when and how to use them.

build-nvidia-kernelversion 20080609.0
install-nvidia-debian   version 20080206.0