Story / scenario opener
You boot Fedora and the desktop loads, but the resolution is stuck at 1024x768. Or you launch a GPU application and it crashes with a missing library error. Or you just upgraded the kernel and the system hangs at the login screen. The root cause is almost always the same: the proprietary NVIDIA driver is not active. Fedora ships with the open-source nouveau driver by default. nouveau provides basic display output but lacks performance, power management, and compute support for modern NVIDIA GPUs. You need the proprietary driver to unlock the hardware. Checking the driver status is the first step before troubleshooting. You must verify the hardware, the kernel module, and the userspace libraries independently. Each layer can fail without breaking the others. Run the checks below to pinpoint exactly where the stack is working and where it is broken.
What's actually happening
The NVIDIA driver stack has three distinct layers. The hardware layer is the GPU chip sitting in your PCIe slot. The kernel layer is the nvidia module that runs in the kernel and talks to the hardware. The userspace layer is the collection of libraries and tools that applications link against. A failure in any layer breaks the system, but the symptoms differ.
If the hardware is missing, lspci will not show the card. This is rare and usually indicates a physical connection issue or a BIOS setting. If the kernel module is missing, nvidia-smi fails with a command not found or a module error. The system falls back to nouveau or modesetting. You get low resolution and poor performance. If the userspace libraries are missing, nvidia-smi works but applications crash with libnvidia-*.so errors. This happens when the driver packages are partially installed or corrupted.
The akmod package is the mechanism Fedora uses to build the kernel module. akmod stands for automatic kernel module. It compiles the driver source against the running kernel on your system. This ensures the module matches the kernel exactly. When you update the kernel, akmod rebuilds the module automatically. If the build fails, the module is not loaded. This is a common failure point after kernel updates. The build process writes logs to /var/log/akmods.log. Check that file if the module is missing after an update.
The fix or how-to
Start by confirming the hardware is detected. This rules out physical issues and shows which driver the kernel is currently using.
Here's how to list the GPU hardware and see the active kernel driver.
lspci -nnk | grep -iA3 nvidia
# WHY: -nn shows vendor IDs for precise matching. -k shows the kernel driver in use. -A3 prints three lines after the match to capture driver info.
The output shows the GPU name and a line starting with Kernel driver in use. If it says nouveau or modesetting, the proprietary driver is not loaded. If it says nvidia, the module is active. Note the Kernel modules line. It lists all modules that can bind to this device. nvidia should be in that list.
Next, query the driver directly. This confirms the module is loaded and returns version information.
Here's how to check the driver version and GPU status.
nvidia-smi
# WHY: Queries the NVIDIA kernel module directly. Returns driver version, GPU utilization, memory, and compute mode. Fails if the module is not loaded.
If nvidia-smi is not found, the driver is not installed. Install the driver packages.
Here's how to install the NVIDIA driver and CUDA libraries.
sudo dnf install akmod-nvidia xorg-x11-drv-nvidia-cuda
# WHY: akmod-nvidia builds the kernel module against the running kernel. xorg-x11-drv-nvidia-cuda provides userspace libraries and X11 support.
The installation triggers the akmod build. This takes a minute. The system compiles the module and installs it. Reboot the system to load the new module.
Here's how to verify the kernel module is loaded.
lsmod | grep nvidia
# WHY: Lists loaded kernel modules. Confirms the driver is active in the kernel. Shows dependencies like nvidia_uvm and nvidia_drm.
You should see nvidia, nvidia_uvm, and nvidia_drm. nvidia_uvm handles unified memory for CUDA. nvidia_drm handles display modesetting. If nvidia_drm is missing, Wayland will not work.
Here's how to check the installed packages.
rpm -qa | grep nvidia
# WHY: Lists installed RPM packages. Verifies the driver files are present on disk. Useful if the module fails to load due to a build error.
The output should include akmod-nvidia, xorg-x11-drv-nvidia, and nvidia-driver-NVRM. The version numbers must match. A mismatch indicates a partial update. Run sudo dnf upgrade --refresh to sync the packages.
Verify it worked
Run nvidia-smi again. The output should look like this.
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.154.05 Driver Version: 535.154.05 CUDA Version: 12.2 |
|-------------------------------+----------------------+----------------------+
| GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. |
|===============================+======================+======================|
| 0 NVIDIA GeForce ... Off | 00000000:01:00.0 On | N/A |
| N/A 45C P8 15W / N/A| 512MiB / 8192MiB | 0% Default |
+-------------------------------+----------------------+----------------------+
The Driver Version line shows the installed driver. The CUDA Version line shows the highest CUDA version the driver supports. This is not the CUDA toolkit version. Applications can use any CUDA version up to this limit. The Disp.A column shows On if the display is active. Persistence-M shows Off by default. Persistence mode keeps the driver loaded when no apps are running. Enable it for server workloads to reduce startup latency.
Run lsmod | grep nvidia to confirm the module dependencies. You should see nvidia_drm listed. Without nvidia_drm, the system cannot use Wayland with NVIDIA. Fedora defaults to Wayland. You must enable modesetting to use Wayland.
Here's how to enable modesetting in GRUB.
# Edit /etc/default/grub
# Add nvidia-drm.modeset=1 to GRUB_CMDLINE_LINUX
# Example: GRUB_CMDLINE_LINUX="... nvidia-drm.modeset=1"
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
# WHY: Regenerates the GRUB configuration file with the new kernel parameters. Required for changes to take effect on boot.
Reboot the system. The parameter persists across kernel updates. Edit /etc/default/grub, never /boot/grub2/grub.cfg directly. The latter is generated and overwritten on updates.
Common pitfalls and what the error looks like
Secure Boot is the most common blocker. Fedora enables Secure Boot by default on UEFI systems. The NVIDIA module is not signed with a key trusted by the firmware. The kernel refuses to load unsigned modules when Secure Boot is active. You will see this error in the boot log.
kernel: nvidia: loading out-of-tree module taints kernel.
kernel: nvidia: module license 'NVIDIA' taints kernel.
kernel: nvidia: module verification failed: signature and/or required key missing - tainting kernel
The module fails to load. nvidia-smi returns NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver. You must enroll a Machine Owner Key (MOK) or disable Secure Boot. Enrolling the MOK is the recommended approach. It maintains the security benefits of Secure Boot while allowing the driver to load.
Here's how to enroll the MOK key.
sudo dnf install mokutil
# WHY: mokutil provides tools to manage Machine Owner Keys. Required for Secure Boot enrollment.
sudo /usr/libexec/nvidia-modeset-key-enroll
# WHY: Generates a key pair and starts the MOK enrollment process. Follow the prompts to set a password.
Reboot the system. The MOK manager interface appears during boot. Select Enroll MOK, enter the password you set, and confirm. The key is now trusted. The driver loads on subsequent boots.
Another pitfall is the akmod build failure. This happens when kernel headers are missing or the kernel version mismatches. Check the build log.
Here's how to check the akmod build log.
cat /var/log/akmods.log
# WHY: Contains the output of the kernel module build process. Shows errors if the build failed.
Look for error: lines. Common errors include kernel-devel not found or gcc version mismatch. Install the missing packages.
sudo dnf install kernel-devel kernel-headers
# WHY: Provides kernel headers and development files. Required for building out-of-tree modules.
Force a rebuild.
sudo akmods --force
# WHY: Rebuilds all akmod packages. Useful after fixing build dependencies or kernel updates.
Reboot the system. The module loads if the build succeeds.
When to use this vs alternatives
Use lspci -nnk when you need to confirm the GPU hardware is detected and see which kernel driver is currently bound to it.
Use nvidia-smi when you need the driver version, GPU health, memory usage, and process list.
Use lsmod | grep nvidia when nvidia-smi fails and you need to verify if the kernel module is loaded or missing.
Use rpm -qa | grep nvidia when you suspect the driver packages are corrupted or missing from the filesystem.
Use modinfo nvidia when you need to check the module version and parameters without loading it.
Use journalctl -xe when the driver fails to load and you need to read the kernel error messages.
Use cat /var/log/akmods.log when the module is missing after a kernel update and you suspect a build failure.
Use mokutil --list-enrolled when you need to verify that the MOK key is enrolled for Secure Boot.
Where to go next
- How to Enable NVIDIA CUDA on Fedora for GPU Computing
- How to Enable Wayland with NVIDIA Drivers on Fedora
- Install AMD GPU drivers
Reboot after kernel updates. The akmod rebuild happens on boot, not on install. Enroll the MOK key. Secure Boot blocks unsigned modules by design. Check akmods.log before reinstalling. Most build failures are missing dependencies, not broken packages.