You plugged in your laptop and the dedicated GPU stays idle
You just booted your new Fedora laptop and noticed the NVIDIA GPU sitting idle in the system monitor. You launch a heavy application or a game, and the frame rate stutters while the CPU spikes to ninety percent. You tried installing the proprietary drivers, but the desktop environment still routes everything through the integrated graphics. The system is working exactly as designed, but you need to tell it when to switch to the dedicated hardware.
What is actually happening under the hood
Hybrid graphics, commonly called Optimus on laptops, splits rendering work between two chips. The integrated GPU handles the desktop compositor, window management, and low-power tasks. The discrete NVIDIA GPU stays powered down until an application explicitly requests it. This design preserves battery life and reduces thermal output. Fedora does not automatically route every window to the faster chip. Instead, it relies on an offloading mechanism that lets you launch specific programs on the dedicated hardware.
Think of the integrated GPU as a standard kitchen and the NVIDIA chip as a commercial oven. You do not fire up the commercial oven to boil water. You use it only when the recipe demands high heat. The prime-run command is the switch that tells the system to route a specific application to the commercial oven.
The underlying technology is called PRIME offloading. The display server renders the desktop on the integrated chip. When you prefix a command with prime-run, the wrapper sets environment variables that tell the application to initialize its OpenGL or Vulkan context on the NVIDIA device. The rendered frames are then copied back to the integrated GPU for display. This avoids the performance penalty of running the entire desktop session on the discrete chip while still giving compute-heavy applications full access to the dedicated hardware.
Convention aside: Fedora separates user configuration from package defaults. Files in /etc/ are safe to edit. Files in /usr/lib/ ship with the package and get overwritten on updates. Never modify files in /usr/lib/. The prime-run wrapper lives in /usr/bin/ and reads its configuration from /usr/share/prime/prime-run.conf. You do not need to touch that file.
Install the driver stack and compile the kernel module
Fedora ships with the open-source nouveau driver enabled by default. The proprietary NVIDIA driver replaces it at the kernel level. Modern Fedora handles the transition automatically through the akmod-nvidia package. The akmod system compiles the kernel module on first boot, matching your exact kernel version. This means you do not need to rebuild drivers after every kernel update.
Here is how to install the driver stack and verify the offloading wrapper.
sudo dnf install akmod-nvidia xorg-x11-drv-nvidia-cuda kernel-devel gcc # WHY: akmod-nvidia pulls the proprietary driver and kernel module builder. kernel-devel and gcc are required for the module to compile on first boot.
sudo reboot # WHY: The akmod system needs a fresh boot cycle to compile and load the nvidia kernel module.
After the reboot, the system loads the proprietary driver. You can now offload applications. The prime-run wrapper sets the necessary environment variables and launches the target program on the discrete GPU.
prime-run glxinfo | grep "OpenGL renderer" # WHY: glxinfo queries the graphics stack. The grep filter isolates the active renderer string.
The output should display NVIDIA GeForce ... instead of Intel(R) .... If you see the Intel string, the offload wrapper is not active or the driver failed to load.
Convention aside: dnf upgrade --refresh is the normal weekly maintenance command. It forces the package manager to check for newer metadata and applies security patches. dnf system-upgrade is for crossing major Fedora releases. They are different commands. Don't conflate them. Run dnf upgrade --refresh before installing new hardware drivers to ensure your kernel headers are current.
Verify the offloading pipeline
Run the offload command against a real application to confirm the pipeline is active.
prime-run glxgears # WHY: glxgears is a lightweight OpenGL test. It will render using the NVIDIA GPU when prefixed with prime-run.
Watch the frame counter stabilize. Open a terminal and run nvidia-smi to see the process listed under the GPU utilization table. The command shows memory usage, temperature, and active processes. If your application appears in the table, the offloading chain is complete.
Check the process list before you close the test window. If the GPU shows zero utilization, the application is still falling back to the integrated chip.
For desktop applications, you can make the offloading persistent by editing the application's .desktop file. Locate the file in /usr/share/applications/ or ~/.local/share/applications/. Copy it to your local directory to avoid package manager overwrites. Edit the Exec= line and prepend prime-run.
[Desktop Entry]
Name=Heavy Application
Exec=prime-run /opt/app/bin/heavy-app # WHY: The desktop environment reads this line to launch the program. Prepending prime-run ensures every GUI launch uses the discrete GPU.
Icon=heavy-app
Type=Application
Save the file and log out. The next time you launch the application from the menu, it will automatically route to the NVIDIA chip.
Reboot before you debug. Half the time the symptom is gone after a fresh module load.
Common pitfalls and what the error looks like
The most frequent failure occurs during the initial kernel module compilation. The akmod system requires matching kernel headers and a working C compiler. If the compilation fails, the system falls back to nouveau and the NVIDIA chip remains invisible to the desktop environment.
Error: Transaction test error: package kernel-devel-6.8.5-200.fc39.x86_64 requires kernel = 6.8.5-200.fc39, but installed kernel is 6.8.6-200.fc39
This mismatch happens when you run dnf upgrade without rebooting. The package manager installs the new kernel headers, but the running kernel is still the old version. Reboot the system and run the installation command again. The headers will match the running kernel, and the module will compile.
Secure Boot is another common blocker. The akmod system signs modules with a locally generated key. If Secure Boot is enabled in the UEFI firmware, the kernel refuses to load unsigned modules. You will see a boot hang or a fallback to the open-source driver. Disable Secure Boot in the firmware settings, or enroll the MOK key when prompted during the first boot after installation. The blue MOK management screen appears before the GRUB menu. Follow the prompts to register the new key.
Wayland compositors handle GPU offloading differently than X11. Fedora Workstation defaults to Wayland. The prime-run wrapper works on both, but some older applications expect X11 environment variables. If an application crashes or shows a black screen, run it with __GLX_VENDOR_LIBRARY_NAME=nvidia prime-run <command>. The explicit vendor library flag forces the correct OpenGL implementation.
Read the journal before guessing. Run journalctl -xeu nvidia-persistenced.service to see why the daemon failed. The x flag adds explanatory text and the e flag jumps to the end. Most sysadmins type this muscle-memory style when a service drops.
When to use this vs alternatives
Use prime-run when you want per-application GPU offloading without changing the desktop compositor. Use the GNOME NVIDIA Offload extension when you prefer a right-click context menu to launch applications on the discrete GPU. Use prime-select nvidia only when you are running a legacy X11-only workflow and want the entire desktop session to run on the NVIDIA chip. Stay on the default prime-run setup if you value battery life and only need the dedicated GPU for specific workloads.
Trust the package manager. Manual file edits drift, snapshots stay.