If you owned an Nvidia Optimus laptop in 2013 and ran Ubuntu, you almost certainly knew about Bumblebee — the community project that made GPU switching work on Linux years before Nvidia provided any official support. Bumblebee worked, but configuring it meant hand-editing /etc/bumblebee/bumblebee.conf and its companion Xorg snippet, where a wrong option could leave you with a black screen or a GPU that refused to initialise. Bumblebee Configurator was a small but valuable utility that wrapped those configuration files in a graphical interface: point, click, save, restart the Bumblebee daemon, and test. This guide covers installing both Bumblebee and its Configurator on Ubuntu 12.04 through 13.04, walking through the settings that actually matter, verifying that GPU offloading works, and troubleshooting the most common failure modes. We have configured Bumblebee on a wide range of Optimus laptops — ThinkPads, Dell Inspirons, Asus ROG machines, and various Acer models — and the Configurator made iterating on driver settings dramatically less painful. For a broader look at Optimus on Ubuntu (including the modern PRIME approach that superseded Bumblebee), see our Nvidia Optimus guide.
How Bumblebee Works
Understanding the architecture helps make the Configurator’s settings meaningful. Here is the quick version:
In an Optimus laptop, the Intel GPU is physically connected to the display. The Nvidia GPU can render frames, but it cannot push them to the screen on its own — they have to be copied to the Intel GPU’s framebuffer first. This is the core problem.
Bumblebee’s solution involved several pieces working together:
- bumblebeed — a daemon that manages the Nvidia GPU’s power state. When no application needs the Nvidia GPU, bumblebeed can power it down to save battery. When optirun or primusrun is called, it powers the GPU up and initialises a secondary X server on it.
- optirun — a launcher that starts an application using VirtualGL. VirtualGL intercepts OpenGL calls from the application, redirects them to the Nvidia GPU’s X server, renders the frame there, reads it back, and composites it onto the Intel GPU’s X server display.
- primusrun — an alternative launcher that uses the Primus library instead of VirtualGL. Primus is more efficient because it avoids the full VirtualGL frame-copying overhead — it renders on the Nvidia GPU and uses the Intel GPU to display, with less latency.
The configuration files (/etc/bumblebee/bumblebee.conf and /etc/bumblebee/xorg.conf.nvidia) control which driver Bumblebee uses (nouveau or nvidia proprietary), how the secondary X server is configured, power management behaviour, and the bridge library (VirtualGL or Primus).
Installing Bumblebee
Before installing the Configurator, you need a working Bumblebee setup.
Step 1: Install Bumblebee and the Nvidia Driver
sudo add-apt-repository ppa:bumblebee/stable
sudo apt-get update
sudo apt-get install bumblebee bumblebee-nvidia primus linux-headers-generic
This installs:
- The Bumblebee daemon and optirun
- The Nvidia proprietary driver integration for Bumblebee
- Primus (for primusrun, which is faster than optirun’s VirtualGL)
- Linux headers (needed for DKMS to build the Nvidia kernel module)
Step 2: Add Your User to the Bumblebee Group
sudo usermod -aG bumblebee $USER
Log out and back in for the group membership to take effect. Bumblebee restricts GPU access to users in this group.
Step 3: Verify Bumblebee Works
optirun glxinfo | grep "OpenGL renderer"
This should output your Nvidia GPU model. If it shows the Intel GPU instead, or if it throws an error, Bumblebee is not working correctly — check the troubleshooting section below before proceeding.
Installing Bumblebee Configurator
With Bumblebee confirmed working, install the Configurator:
sudo add-apt-repository ppa:bumblebee-configurator/stable
sudo apt-get update
sudo apt-get install bumblebee-configurator
Launch it from the application menu (look under System or System Tools) or from the terminal:
sudo bumblebee-configurator
Root access is required because the configuration files are in /etc/bumblebee/ and owned by root.
Navigating the Configurator
The Configurator’s interface is organised into tabs that map to sections of bumblebee.conf:
General Tab
Driver — choose between nvidia (proprietary) and nouveau (open-source). For any serious GPU work — gaming, CUDA, OpenCL — use nvidia. The nouveau driver supports Optimus offloading but with significantly lower performance and no CUDA support.
Bridge — choose between auto, virtualgl, and primus. Set this to primus if you installed the primus package. It is faster and uses less CPU than VirtualGL.
TurnCardOffAtExit — controls whether Bumblebee powers down the Nvidia GPU when no application is using it. Set to true to save battery. Set to false if you are debugging and want the GPU to stay on.
PMMethod — the power management method for the Nvidia card. Options include bbswitch (recommended, uses the bbswitch kernel module to cut power to the GPU via ACPI), switcheroo (uses the kernel’s vga_switcheroo interface), and none (no power management — the GPU stays on always). If bbswitch is installed (it should be if you installed from the PPA), use it.
Nvidia Xorg Tab
This tab maps to /etc/bumblebee/xorg.conf.nvidia — the Xorg configuration used for the secondary X server that runs on the Nvidia GPU.
BusID — the PCI bus address of your Nvidia GPU. The Configurator auto-detects this, but verify it matches the output of lspci | grep -i nvidia. It should be something like PCI:01:00:0. Getting this wrong is the single most common reason Bumblebee fails.
Driver — should match the driver in the General tab. Usually nvidia.
Module paths — the paths to the Nvidia driver’s GLX and X11 modules. The Configurator fills these in based on the installed driver version. If you upgrade the Nvidia driver and Bumblebee stops working, these paths may need updating.
Applying Changes
After modifying settings, click “Save” in the Configurator. Then restart the Bumblebee daemon for changes to take effect:
sudo service bumblebeed restart
Test with:
optirun glxinfo | grep "OpenGL renderer"
If you switched from VirtualGL to Primus, test with primusrun as well:
primusrun glxinfo | grep "OpenGL renderer"
Verifying GPU Offloading in Practice
The glxinfo check confirms the GPU is accessible, but for a practical test, try a 3D application:
primusrun glxgears
Watch the frame rate in the terminal output. On the Nvidia GPU via Primus, you should see several thousand FPS (glxgears is a trivial benchmark). Compare it to:
glxgears
Without primusrun, glxgears runs on the Intel GPU, and on integrated graphics from the 2012–2013 era, frame rates were notably lower.
For games, prefix the launch command:
primusrun wine GameExecutable.exe
primusrun ./game-binary
Or for Steam, set the launch options for a game to: primusrun %command%
Common Pitfalls
“Cannot access secondary GPU” error. This typically means the BusID in the Xorg configuration does not match the actual PCI address of your Nvidia card. Open the Configurator’s Nvidia Xorg tab and verify the BusID matches lspci | grep -i nvidia output. Remember the format difference: lspci shows 01:00.0 (with a dot), while Bumblebee’s Xorg config uses PCI:01:00:0 (with colons).
Black screen after reboot. If changing Bumblebee settings causes a black screen at login, the secondary X server configuration may be conflicting with the primary X server. Boot into recovery mode (hold Shift at GRUB), get a root shell, and restore the backup configuration files. The Configurator creates backups in /etc/bumblebee/ with .bak extensions. Alternatively, reset bumblebee.conf to defaults by reinstalling: sudo apt-get install --reinstall bumblebee.
bbswitch fails to load. If the bbswitch kernel module does not load (check with lsmod | grep bbswitch), it may not have been built for your current kernel. Reinstall it: sudo apt-get install --reinstall bbswitch-dkms and then sudo modprobe bbswitch. If DKMS fails to compile, you are likely missing linux-headers-$(uname -r).
optirun works but primusrun does not. Make sure the primus package is installed. On 64-bit systems, also install the 32-bit libraries if you are running 32-bit applications (like many games): sudo apt-get install primus-libs:i386.
GPU does not power down. Check power management: cat /proc/acpi/bbswitch should show 0000:01:00.0 OFF when no optirun/primusrun process is active. If it shows ON, the PMMethod setting in the Configurator may be wrong, or another process is keeping the GPU awake. Some ACPI implementations on specific laptop models had compatibility issues with bbswitch — check dmesg | grep bbswitch for error messages.
Driver version mismatch after apt upgrade. When Ubuntu pushes a new Nvidia driver version through updates, the module paths in Bumblebee’s Xorg configuration may point to the old version’s directory. If optirun suddenly stops working after an update, open the Configurator’s Nvidia Xorg tab and verify the module paths reflect the currently installed driver version. You can check what is installed with dpkg -l | grep nvidia.
The Legacy Context
Bumblebee and its Configurator were essential tools in the 2012–2015 era, when Nvidia provided zero official support for Optimus on Linux. The project was a remarkable community effort — it made GPU switching functional on hardware that Nvidia seemingly did not care about supporting. By 2019, Nvidia finally added PRIME render offloading to their proprietary driver (version 435+), and Ubuntu 19.10 was the first release to support it natively. Today, PRIME is the recommended approach, and Bumblebee is legacy. But for anyone maintaining an older Optimus laptop on Ubuntu 12.04 or 13.04, or studying the history of Linux hardware support, Bumblebee Configurator remains a useful reference for how the community solved a problem the vendor refused to address.