This blueprint is about improving user experience with proprietary drivers such as fglrx and nvidia. These will make installation, uninstallation, and fault handling more seamless and clean for users. We also identify improvements for testing, documentation, and packaging to help us avoid or find problems more reliably before release.


These drivers use their own libraries which cannot be shared with open source drivers and involve building/installing kernel modules. Mixing libraries can break the system in different ways. For this reason (currently) no more than one proprietary driver can be installed at the same time and, in order to go back to using open source driver, the uninstallation of the proprietary one is required. The use of diversions complicates things and the system can be left in a miserable state if updates go wrong or if users install the nvidia driver from Nvidia's installer.

In all these cases users are left without a clue about what happened to their system. This page is about improving the current situation and informing users when something goes wrong.

Compounding the matter, we receive rebuild drivers from the vendors rather late in our development process. Due to this fact, most Ubuntu developers are using the open drivers. This results in few people doing testing, and a short window of time in which to respond to test findings.

Use Cases

  • Gina downloads and installs the latest -nvidia driver from Nvidia's website. Ubuntu informs her that in order to do this, her existing Ubuntu-provided driver needs uninstalled, and offers to do this for her.
  • Ashley has a laptop with two nvidia chips, one late model chip for high performance, and one old chip for low power situations. Unfortunately the old chip only works with a legacy nvidia driver, which has made it challenging for her to switch between the two chips. In Lucid, she can install both the current and legacy drivers and switch between video cards as she desires.


This specification covers enhancements to the proprietary video drivers -nvidia and -fglrx that are provided in the Ubuntu distribution. No other video drivers are affected.

Ensure DKMS builds driver before GDM boots it

dkms should start before gdm if needed for video driver as in bug 453365.

(See LP: #474917, #438398, #453365)

Implementation Tasks

Apport Script Improvements

Implementation Tasks

  • Include make.log file(s)
  • Include dkms status

Packaging Documentation

Because of the nature of the proprietary drivers, they have some unique packaging procedures. -fglrx has documented its procedure to fairly "paint by numbers". We need to do similarly for -nvidia.

Implementation Tasks

  • Write packaging documentation for the -nvidia package
    • Follow fglrx's debian/README as an example
    • Include directions on how to patch the package

Load -nvidia and -fglrx by default if installed

Most of the open source drivers will load by default if they're installed due to automatic detection in the xserver. Any special driver-specific or hardware-specific configuration settings are likewise applied automatically. This is not done for proprietary drivers upstream, but we can patch it in at the distro level.

Implementation Tasks

  • Fix logic in patches 104 and 105 to correctly select -nvidia when appropriate and xorg.conf is present with no Driver specified
  • Same as above when xorg.conf is missing
  • Ensure fallbacks work if nvidia/fglrx is failing to load
  • Automatic configuration
    • Identify logic in jockey which inserts configuration into xorg.conf
    • Create analogous logic in xserver

Proprietary Driver Testing

Since we have limited time and testers during the development cycle, it may help to provide a step-by-step guide that walks the user through installing and uninstalling, checking basic functionality, and checking the fault handling.

Implementation Tasks

Using Alternatives instead of Diversions

This aims to solve issues such as GL libraries getting overwritten when installing a proprietary driver, as discussed in bug 258038

  1. Libraries:

    • The libraries (e.g.,,, etc.) that come with each driver are stored in /usr/lib/$PROPRIETARY_DRIVER_NAME/ (e.g. nvidia-current)
    • /etc/ points to /etc/ (for open drivers) or to /etc/$PROPRIETARY_DRIVER_NAME/
    • Modules and extensions (e.g.,,, etc.) are stored in /usr/lib/$PROPRIETARY_DRIVER_NAME/xorg/
    • Call ldconfig after updating alternatives.
  2. Kernel Modules:

    • Different flavours of the same driver have kernel modules with different names (e.g. nvidia-current.ko, nvidia-96.ko, etc.)(e.g. DEST_MODULE_NAME[0]="nvidia-current" in dkms.conf)
    • The sources of the several flavours live in different directories (e.g. /var/lib/dkms/nvidia-current, /var/lib/dkms/nvidia-96) (e.g. PACKAGE_NAME="nvidia-current" in dkms.conf)
    • /etc/modprobe.d/$PROPRIETARY_DRIVER_NAME.conf points to /etc/$PROPRIETARY_DRIVER_NAME/modprobe.conf. This simply sets an alias for the driver flavour (e.g. "alias nvidia nvidia-current") so that the kernel module can be recognised as, say, nvidia)
  3. Configuration Panels and Other binaries:

    • Additional binaries (e.g. nvidia-settings, amdcccle, etc.) are stored in /usr/lib/$PROPRIETARY_DRIVER_NAME/bin/. This makes sure that users don't end up with the Nvidia configuration panel when they have loaded the fglrx driver.
    • [Optional] Make nvidia-settings and amdcccle load users settings when the session starts. Maybe this can be done with a script in /etc/X11/Xsession.d/ (which would be part of the alternatives system)

  4. Hardware Changes Detection:

    • What happens when users swap their cards with other cards which are supported by different drivers (or different driver flavours of the same driver)?
    • We should detect the hardware change (maybe by checking the modaliases?) and inform users about the change.
      • Case 1 - Users install the appropriate driver before plugging in the new card. The alternatives are automatically updated by the installation of the new driver.

      • Case 2 - Users shut down their computer, swap their graphics card with another card and then boot into Ubuntu.

        • Note: We can't update alternatives on boot as things might not work well if we run ldconfig after loading modules. We can't do it before loading modules because the filesystem would be in read-only mode. For this reason the only thing we can do is what follows.

        • We let users enter the X session with either Failsafe X or with a half broken system (no 3D acceleration, no compiz and a laggy UI). Then a dialog pops up and notifies users about the problem and suggests a solution e.g. "Do you want to enable the driver for your new hardware?" Then we act accordingly and ask users to reboot.
  5. Clean up diversions from previous installations:

    • Make sure that diversions from previous installations do not cause problems with updates.
  6. Improve interaction with the Nvidia installer:

    • Implement what NVIDIA's Aaron Plattner suggests in LP: #317703:

      • Install /usr/lib/nvidia/pre-install and /usr/lib/nvidia/failed-install so as to prevent the nvidia-installer from overwriting Ubuntu's nvidia packages if they are installed. Users will be informed by the Nvidia installer that they have to uninstall the Ubuntu packages if they want to use the installer.
      • [Optional] We should add a similar check in the packages so as to make sure that users cannot install the Ubuntu packages without uninstalling the driver from the Nvidia installer.

  7. Change the names of the current Nvidia drivers [Required by point 2.]:

    • nvidia-current (which would stand for the latest driver), nvidia-96 and nvidia-173 (i.e. the 2 legacy drivers)

Workflow for '''point 4'''

  • Transitions:
    • proprietary -> proprietary (e.g. nvidia -> fglrx or nvidia-96 -> nvidia-185)

      • Is the new driver already installed?
        • Yes. Update alternatives, run ldconfig and ask the user to reboot.
        • No. Install the new driver with Jockey (if possible) and reboot.
    • open source -> proprietary (e.g. -ati -> fglrx or -nv -> nvidia-173)

      • Is the new driver already installed?
        • Yes. Update alternatives, run ldconfig and ask the user to reboot.
        • No. Install the new driver with Jockey (if possible) and reboot.
    • proprietary -> open source (e.g. fglrx -> -ati or nvidia-173 -> -nv)

      • Update alternatives, run ldconfig and ask the user to reboot.

Implementation Tasks

  • Store libraries, modules, extensions in /usr/lib/<driver>/

  • Call ldconfig after updating alternatives.
  • Rename kernel modules in dkms.conf
  • Store additional binaries in /usr/lib/<driver>/bin

  • Detect gfx hardware changes (maybe by checking the modaliases?) and inform users about the change.
  • Implement dialog that pops up in Failsafe-X to suggest enabling driver for new hardware
  • Make sure that diversions from previous installations do not cause problems with updates.
  • Implement suggestions from LP: #317703

  • Install /usr/lib/nvidia/pre-install and /usr/lib/nvidia/failed-install
  • Add a check to require uninstalling Nvidia's driver when installing Ubuntu packages
  • Change the names of the current Nvidia drivers to nvidia-current


Old patches that default us to -nvidia and -fglrx (broken):

  • + Bug: Falls back to rendition. Needs a 'break' in switch statement [bryce]


X/ProprietaryDrivers/IntegrationImprovements (last edited 2009-11-25 13:11:35 by host188-230-dynamic)