NVIDIA/Bumblebee

Note
This article was created to consolidate various external guides and How-Tos about using Bumblebee/bbswitch/primus with the proprietary NVIDIA drivers. It is based mainly on the following links:

• DotSlashLinux's Guide (On the way back machine as link was dead)
• Fedeliallalinea's Guide on the Gentoo Forum (Italian)

The Arch Wiki article on Bumblebee is also very comprehensive.

This is a guide to configuring a Gentoo system to make use of Hybrid Graphics using:

• The proprietary NVIDIA graphics drivers
• The Intel iGPU drivers
• Bumblebee
• bbswitch for hardware switching
• Primus for bridging

This configuration prefers Primus over Optirun/VGL.

Pre Installation

NVIDIA Optimus Support

This is pretty much straightforward. If you have an intel processor (2nd Gen +) and a NVIDIA gpu, then you probably have optimus on your laptop. To check for sure, run

root #lspci -k | grep -i -e vga -e nvidia

00:02.0 VGA compatible controller: Intel Corporation Device 591b (rev 04)
01:00.0 3D controller: NVIDIA Corporation GM107GLM [Quadro M1200 Mobile] (rev a2)

and look for VGA or 3D controllers to see your present GPUs. If you don't have an optimus system, this guide will do nothing for you.

Installation

NVIDIA drivers

First configure your system to use NVIDIA's proprietary drivers instead of the open source Nouveau drivers and install the drivers. This is already detailed elsewhere on the wiki and is not repeated here.

Note
It may be useful to set the -kms and -uvm USE Flags before installing the NVIDIA drivers

Intel drivers

Also configure and install the Intel drivers according to the wiki. DDX or modesetting both ought to work.

Kernel

Ensure that you system can load and unload modules:

KERNEL Linux kernel 4.3.3+

CONFIG_MODULES=y
CONFIG_MODULE_UNLOAD=y

Configuring /etc/portage/make.conf

Video Cards

Set your video card variables like so:

FILE /etc/portage/make.conf

...
VIDEO_CARDS="intel i965 nvidia"
...

Note
People with older Intel cards may need to use i915 instead of i965

USE Flags

In order to allow easy enabling and disabling of the NVIDIA drivers, we need to disable the kms and uvm USE flags for the NVIDIA drivers:

FILE /etc/portage/package.use

x11-drivers/nvidia-drivers -kms -uvm

Note
See links for USE flag descriptions: nvidia-drivers, bumblebee, xf86-video-intel.

Recommended USE flags by DotSlashLinux are:

• nvidia-drivers: +X, +acpi, +compat, driver, gtk3, +tools, -kms, -pax_kernel, -static-libs, -uvm, -wayland
• xf86-video-intel: +dri, +dri3, +sna, +udev, +xvmc, -debug, -tools, -uxa
• bumblebee: +bbswitch, +video_cards_nvidia, -video_cards_nouveau

Note
It is possible to use KMS and UVM with Bumblebee, see the item in the troubleshooting section

Now update your @world set:

root #emerge --ask --update --deep --newuse @world

Then reboot your system

root #shutdown -r now

Installing Bumblebee, bbswitch, Primus

Emerge the packages:

root #emerge --ask sys-power/bbswitch x11-misc/bumblebee x11-misc/primus

Configuration

User access to Bumblebee

Make sure to add your user to the video and bumblebee groups to allow use of bumblebee:

root #usermod -a -G video,bumblebee USER

(Replacing USER with your username)

Configuring /etc/init.d/bumblebee

By default, the OpenRC bumblebee module is set to depend on VGL and XDM. We are using primus over VGL. The XDM dependancy can cause problems if this configuration is being setup prior to the X server. Remove the following lines (which should be near the start of the file):

FILE /etc/init.d/bumblebee

...
depend() {
    need xdm
    need vgl
}
...

Your final file should look something like this:

FILE /etc/init.d/bumblebee

PIDFILE="${PIDFILE:-/var/run/bumblebee.pid}"

start() {
    ebegin "Starting BumbleBee Daemon"
        start-stop-daemon -S -p "${PIDFILE}" -x /usr/sbin/bumblebeed -- -D ${BUMBLEBEE_EXTRA_OPTS} --pidfile "${PIDFILE}"
    eend $?
}

stop() {
    ebegin "Stopping BumbleBee Daemon"
        start-stop-daemon -K -p "${PIDFILE}" -R SIGTERM/10
    eend $?
}

The important part is that it no longer has any dependencies.

Configuring /etc/bumblebee/bumblebee.conf

The following settings need to be present in the /etc/bumblebee/bumblebee.conf file.

FILE /etc/bumblebee/bumblebee.conf

[bumblebeed]
...
KeepUnusedXServer=false
...
Driver=nvidia
...

[optirun]
...
Bridge=primus
...
VGLTransport=rgb
...

[driver-nvidia]
...
KernelDriver=nvidia
...
PMMethod=bbswitch
...

Note
The VGLTransport setting is only needed if the reader is attempting to configure bumblebee to work with VGL instead of Primus. It does no harm to set it anyway.

OpenRC

Now enable bumblebe to load at runlevel default

root #rc-update add bumblebee default

And once again, reboot the system:

root #shutdown -r now

Configuring /etc/modprobe.d/nvidia-rmmod.conf

Earlier, we disabled the kms and uvm USE flags for the NVIDIA drivers. This means we should only have the module nvidia present and not nvidia-uvm, nvidia-drm, or nvidia-modeset. In order that modprobe -r nvidia functions correctly, we need it to remove only nvidia and nothing else. Remove all other modules from /etc/modprobe.d/nvidia-rmmod.conf so that it changes from looking like this:

FILE /etc/modprobe.d/nvidia-rmmod.conf

remove nvidia modprobe -r --ignore-remove nvidia-drm nvidia-modeset nvidia-uvm nvidia

to this:

FILE /etc/modprobe.d/nvidia-rmmod.conf

remove nvidia modprobe -r --ignore-remove nvidia

OpenGL

We need to ensure OpenGL is set to use xorg-x11 instead of nvidia:

root #eselect opengl list

[1] nvidia
[2] xorg-x11 *

root #eselect opengl set 2

Post Installation

Check if Bumblebee is Working

Using glxgears

Install the x11-apps/mesa-progs package to access glxgears:

root #emerge --ask x11-apps/mesa-progs

Before we run our test, make sure the nvidia module is not loaded:

root #lsmod

Module    Size   Used by
bbswitch  5461   0

And check the status of bbswitch using:

root #cat /proc/acpi/bbswitch

0000:01:00.0 OFF

As you can see:

• bbswitch is loaded
• The nvidia module is not loaded
• The NVIDIA GPU (at PCI location 01:00.0) is off

Now let’s check if the NVIDIA card will be switched on and the nvidia module will be loaded once optirun/primusrun are executed, and if it’ll switch off and the nvidia module will be unloaded once optirun/primusrun finish executing.

From within an Xorg Session:

user $optirun glxgears

or (but not both at once):

user $primusrun glxgears

Note
primusrun reputedly gives better performance than optirun

A window showing glxgears should open. While it's running, check:

root #lsmod

Module        Size   Used by
nvidia    10652360   51
bbswitch      5461   0

root #cat /proc/acpi/bbswitch

0000:01:00.0 ON

This shows that the NVIDIA GPU is now on, its module loaded, and OpenGL is using it as expected. Once you end the optirun or primusrun command and exit glxgears, the previous checks run again should show the GPU off and the module unloaded.

Note
If your card did not turn off when glxgears exited, try the following:

root #rmmod nvidia && echo "OFF" >> /proc/acpi/bbswitch

Using glxinfo

Alternatively, glxinfo can be used to see if bumblebee is working:

root #glxinfo | grep OpenGL

OpenGL vendor string: Intel Open Source Technology Center
OpenGL renderer string: Intel Mesa DRI (R) Skylake Halo GT2
OpenGL core profile version string: 3.3 (Core Profile) Mesa 11.0.6
OpenGL core profile shading language version string: 3.30
OpenGL core profile context flags: (none)
OpenGL core profile profile mask: core profile
OpenGL core profile extensions:
OpenGL version string: 3.0 Mesa 11.0.6
OpenGL shading language version string: 1.30

root #primusrun glxinfo | grep OpenGL

OpenGL vendor string: NVIDIA Corporation
OpenGL renderer string: GeForce GTX 960M / PCIe / SSE2
OpenGL core profile version string: 4.4.0 NVIDIA 361.28
OpenGL core profile shading language version string: 4.40 NVIDIA via Cg compiler
OpenGL core profile context flags: (none)
OpenGL core profile profile mask: core profile
OpenGL core profile extensions:
OpenGL version string: 4.5.0 NVIDIA 361.28
OpenGL shading language version string: 4.50 NVIDIA

As you can see, running the command without primusrun runs with the iGPU but with primusrun runs with the NVIDIA GPU.

Building with KMS and UVM

Users who want to use CUDA or offloading with their NVIDIA GPU will want to use KMS and UVM. To do this, first follow the guide above to install without KMS and UVM. This provides a good starting point because if it doesn't work with that setup, it will not work with this one.

First, stop the bumblebee daemon:

root #killall bumblebeed

Then unmount the bbswitch module and remount nvidia module:

root #modprobe -r bbswitch

root #modprobe nvidia

Next, change your use flags to include kms and uvm:

FILE /etc/portage/package.use

x11-drivers/nvidia-drivers kms uvm

and update your @world set:

root #emerge --ask --update --deep --newuse @world

Next, enable the seden overlay with eselect repository or layman:

root #eselect repository enable seden

root #emerge --sync seden

or

root #layman -a seden

and install the patched version of bumblebee (which is capable of removing all of the NVIDIA drivers):

root #emerge --ask x11-misc/bumblebee::seden

Edit the nvida-rmmod.conf to unload the relevant drivers in the right order:

FILE /etc/modprobe.d/nvidia-rmmod.conf

remove nvidia modprobe -r --ignore-remove nvidia-drm nvidia-modeset nvidia-uvm nvidia-drm nvidia

Change your kernel module parameter in your bumblebee.conf file to nvidia-uvm

FILE /etc/bumblebee/bumblebee.conf

[driver-nvidia]
...
KernelDriver=nvidia-uvm
...

Now reboot your system.

Using Bumblebee with Steam Games

In order to run a Steam game with optirun or primusrun, you need to

• right click on the game within steam
• select "properties"
• "Set Launch Options"
• add either optirun %command% or primusrun %command% to the text field.

Using the Bumblebee Overlay

Some users cannot get this configuration to work and it is suggested to use the Bumblebee Overlay to emerge bumblebee and primus.

Note
The last commit on the Bumblebee Overlay github was in 2016, while the last update of x11-misc/bumblebee was in 2018.

Note
Alternatively, some users recommend the Seden Overlay, see Yamakuzure's post on this thread. This has support for kms and uvm.

First add the bumblebee overlay via eselect repository or layman:

root #eselect repository enable bumblebee

root #emerge --sync bumblebee

or

root #layman -a bumblebee

Then unmask bumblebee and primus:

root #echo "= x11-misc / bumblebee-9999 ~ amd64" >> /etc/portage/package.accept_keywords/bumblebee

root #echo "= x11-misc / primus-9999 ~ amd64" >> /etc/portage/package.accept_keywords/bumblebee

And mask the official Portage Tree:

root #echo "x11-misc / bumblebee :: gentoo" >> /etc/portage/package.mask/bumblebee.gentoo

Then emerge Primus:

root #emerge --ask x11-misc/primus

Configuring Xorg

Some systems require Xorg to be configured to use the Intel drivers. Do this according to the Gentoo Intel Wiki Page.

Troubleshooting

bbswitch refuses to turn off card

Try adding:

root #"acpi_osi=!Windows\x202013" acpi_osi=Linux nogpumanager i915.enable_hd_vgaarb=1 enable_hd_vgaarb=1

to your kernel command-line (this has worked for a couple of users, especially those with Thinkpads and Lenovo laptops).

Manual Unloading

If the NVIDIA drivers are buildt with kms and/or uvm and a patched version of bumblebee then the bumblebee module will not be able to unload the nvidia module as it will be in use by the nvidia-modeset module which is itself in use by the nvidia-drm module. However, the modules cat be unloaded manually (using modprobe -r) and the relevant changes to /etc/modprobe.d/rmmod-nvidia.conf. The GPU can then be turned off using tee /proc/acpi/bbswitch<<<OFFF. Some users have these two commands in a script accessible through a key command in their WM.

System Freezes when Starting Xorg Server

On some systems, it may be necessary to start Xorg with the nvidia module loaded and the discrete GPU turned on or else the system will hang. The module can then be unloaded and the GPU switched off. In order to manually load the module, add nvidia to your modules configuration file:

FILE /etc/conf.d/modules

modules="nvidia"

The nvidia module must not be blacklisted.

Bumblebee Daemon Doesn't Start On Boot

First check that bumblebee is configured in OpenRC: Now enable bumblebe to load at runlevel default

root #rc-update add bumblebee default

If you still get errors indicating that the Bumblebee Daemon is not running when you attempt optirun and primusrun commands, it may be necessary to start the daemon manually on log-in. Put exec bumblebee --daemon into a suitable configuration file so that it will be automatically run when you start your X server. This might be in your .xinitrc or window manager (such as i3) config file depending on your setup.

GPU doesn't automatically turn off for the first time

Some users may experience their bumblebee setup working in every respect except for that the GPU remains on until the first time a primusrun or optirun command is run. A workaround for this is to add primusrun glxinfo to your .xinitrc or other initialising config file (like your i3 config file).

System Hangs on any PCI call when the GPU is off

Some users may find that their setup works well but will experience random kernel crashes characterized by a complete system hang with no errors in any log files generated. If this is the case, it may be necessary to trick the acpi kernel module into thinking that the system is an earlier version of Windows by editing your grub configuration:

FILE /etc/default/grub

GRUB_CMDLINE_LINUX_DEFAULT='acpi_rev_override=5 acpi_osi="Windows 2009"'

Important
Your grub config file may use double (") or single (') quotes. Either will work, but ensure that the other is used for the Windows 2009 string else you will terminate the kernel command line prematurely.

The parameters modprobe.blacklist=nvidia, nvidia.modeset=0, and pcie_port_pm=off may also be necessary.

Then regenerate your grub config file:

root #grub-mkconfig -o /boot/grub/grub.cfg

Blacklisting the NVIDIA Modules

On some systems it may be necessary to blacklist the nvidia modules. Edit your blacklist file as necessary:

FILE /etc/modprobe.d/blacklist.conf

blacklist nvidia
blacklist nvidia-modeset
blacklist nvidia-drm
blacklist nvidia-uvm

Could not load GPU driver

If you tested with glxgears to see if Bumblebee is working and got the following output:

user $glxinfo | grep OpenGL

primus: fatal: Bumblebee daemon reported: error: Could not load GPU driver

Restarting the GUI by using killall X && startx should fix the issue.

Specific Use-Cases

The following Wiki Pages make reference to Bumblebee and/or Bumblebee configurations:

• Lenovo ThinkPad T440s
• Clevo P650HS-G
• Dell XPS 15z
• Toshiba Satellite P70-A
• Dell XPS 15 9560

See Also

• x11-misc/bumblebee, The Bumblebee Project, The Bumblebee Github
• sys-power/bbswitch, The bbswitch Github
• x11-drivers/nvidia-drivers, NVidia/nvidia-drivers, NVIDIA, NVIDIA/Optimus
• x11-misc/primus, The Primus Github