From Gentoo Wiki
Jump to: navigation, search

Bumblebee is an open source implementation of NVIDIA Optimus.

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.


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.

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.


Ensure that you system can load and unload modules:

KERNEL Linux kernel 4.3.3+

Configuring /etc/portage/make.conf

Video cards

Set your video card variables like so:

FILE /etc/portage/make.conf
VIDEO_CARDS="intel i965 nvidia"
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
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
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


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 dependency 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

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


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.


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


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
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.

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


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

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.

The last commit on the Bumblebee overlay GitHub was in 2016, while the last update of x11-misc/bumblebee was in 2018.
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


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.


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 built 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/modules-load.d/video.conf

The nvidia module must not be blacklisted.

Bumblebee daemon doesn't start on boot

First check that bumblebee is configured in OpenRC: Now enable Bumblebee 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 initializing 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"'
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.

libGL error: failed to load driver: swrast

If you get the following error when you run optirun:

root #optirun glxinfo
libGL error: No matching fbConfigs or visuals found
libGL error: failed to load driver: swrast
X Error of failed request:  GLXBadContext
  Major opcode of failed request:  150 (GLX)
  Minor opcode of failed request:  6 (X_GLXIsDirect)
  Serial number of failed request:  49
  Current serial number in output stream:  48

The issue could be that Bumblebee cant find the NVIDIA libraries. Changing the LibraryPath in /etc/bumblebee.conf can fix the issue.

FILE /etc/bumblebee/bumblebee.conf

Specific use cases

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

See also

External resources