Story / scenario opener
You downloaded the latest .run installer from the NVIDIA developer site because the repository packages were lagging behind your GPU architecture. You ran the script, the terminal flooded with compilation warnings, and now your system drops to a black screen on boot. The display manager is fighting the new kernel module, and your desktop environment refuses to start. This happens when the installer runs while the X server or Wayland compositor is still active, or when the kernel headers are missing. The fix is straightforward, but it requires stopping the graphical stack first and letting the script handle the build process cleanly.
What is actually happening
Fedora ships with the open-source Nouveau driver enabled by default. Nouveau provides basic display output and allows the installer to boot, but it lacks hardware acceleration and modern Vulkan support. When you run the NVIDIA .run file, the script downloads the proprietary kernel source, compiles it against your running kernel, and installs the user-space libraries. The script also tries to replace the Mesa OpenGL libraries. If you do not tell it to stop, it overwrites system files that DNF manages, which breaks future package updates.
The installer also needs exclusive access to the GPU. If GDM or SDDM is running, they hold the DRM device open. The compilation step will fail with a kernel module load failed error, or worse, it will install the module but leave the display manager pointing at the old Nouveau driver. You end up with a mismatched stack. The manual .run method bypasses Fedora's package manager entirely. That means DNF does not track the files, kernel updates will not automatically rebuild the module, and you must manage the driver lifecycle yourself.
Config files in /etc/ are user-modified. Files in /usr/lib/ ship with the package. Edit /etc/. Never edit /usr/lib/. The NVIDIA installer places configuration snippets in /etc/X11/ and /etc/modprobe.d/. It leaves the compiled binaries in /usr/lib/. If you manually move files between those directories, the package manager will overwrite your changes on the next update.
Convention aside: dnf upgrade --refresh is the normal weekly maintenance command. dnf system-upgrade is for crossing major Fedora releases. They are different commands. Don't conflate them. When you are on a manual .run driver, kernel updates will trigger DKMS automatically. You do not need to rerun the installer unless NVIDIA releases a new version.
The installation procedure
Prepare the system before touching the installer. You need the kernel development headers and a C compiler. The script will fail silently if they are missing.
Here is how to install the build dependencies and verify the kernel headers match your running kernel.
sudo dnf install kernel-devel kernel-headers gcc make # WHY: provides the exact header files and compiler the NVIDIA script needs to compile the kernel module
uname -r # WHY: confirms the running kernel version so you can verify the installed devel package matches
rpm -q kernel-devel-$(uname -r) # WHY: ensures the headers are actually installed for this specific kernel release
Download the .run file to your home directory. Do not run it from a network drive or a directory with spaces in the name. The installer expects a clean path.
Stop the display manager. Fedora uses GDM by default. Stopping it drops you to a text console and releases the GPU for the installer.
Here is how to switch to a virtual console and stop the graphical stack safely.
sudo systemctl isolate multi-user.target # WHY: stops GDM and all graphical sessions without killing your SSH or terminal connection
sudo systemctl stop gdm # WHY: ensures the display manager process is fully terminated before the installer probes the GPU
Navigate to the directory containing the downloaded file. Make it executable if it is not already. Run the installer with the flags that prevent it from overwriting system OpenGL libraries.
Here is the exact command sequence to run the NVIDIA installer with safe defaults.
cd ~/Downloads # WHY: moves into the directory where the file was saved
chmod +x NVIDIA-Linux-x86_64-*.run # WHY: grants execute permission so the script can run
sudo sh NVIDIA-Linux-x86_64-*.run --no-opengl-files --dkms # WHY: skips Mesa library replacement and enables DKMS for automatic kernel rebuilds
The --no-opengl-files flag is mandatory. It tells the script to leave the system OpenGL stack alone. The --dkms flag registers the driver with the Dynamic Kernel Module Support framework. DKMS will automatically recompile the NVIDIA module when you run a kernel update. Without it, your next dnf upgrade will leave you with a black screen.
Follow the on-screen prompts. Accept the EULA. Let the compilation finish. It will take a few minutes depending on your CPU. When it finishes, it will ask if you want to run the distribution-specific script. Say yes. It will configure the initramfs and update the module dependencies.
Restart the system. Do not try to restart GDM manually. A full reboot ensures the kernel loads the new module before the display manager starts.
Reboot before you debug. Half the time the symptom is gone.
Verify it worked
Log back in. Open a terminal and check the kernel module status. The output should show the NVIDIA module loaded and the Nouveau module blacklisted.
Here is how to confirm the driver is active and the GPU is reporting correctly.
lsmod | grep nvidia # WHY: lists loaded kernel modules and confirms the NVIDIA driver is active
nvidia-smi # WHY: queries the GPU directly and prints driver version, memory usage, and compute processes
glxinfo | grep "OpenGL renderer" # WHY: verifies the user-space OpenGL stack is routing through NVIDIA hardware
If nvidia-smi returns a command not found error, the user-space libraries did not install correctly. Check the installation log at /var/log/nvidia-installer.log. If glxinfo shows llvmpipe or Nouveau, your desktop session is still using the open-source driver. Log out completely and log back in, or switch to an X11 session at the login screen. Wayland support for NVIDIA is improving but still requires specific kernel parameters.
Run nvidia-smi before you debug. Half the time the symptom is gone after a full session logout.
Common pitfalls and what the error looks like
Secure Boot is the most common blocker. The NVIDIA .run script compiles a kernel module that is not signed with your machine's MOK key. The kernel will refuse to load it. You will see NVRM: The NVIDIA kernel module is not loaded in the logs. You must enroll a Machine Owner Key during the installation or disable Secure Boot in the firmware setup.
Kernel updates can break the module if DKMS fails. You will see a boot failure or a fallback to the emergency shell. The journal will contain Failed to start NVIDIA Persistence Daemon. Check the DKMS log at /var/lib/dkms/nvidia/VERSION/build/make.log. The build usually fails because the kernel headers are missing or the compiler version changed. Reinstall the headers and run sudo dkms autoinstall.
The installer will refuse to proceed if it detects an existing NVIDIA installation. You will see Another NVIDIA driver is currently in use. You must uninstall the old driver first. Run sudo /usr/bin/nvidia-uninstall before starting the new installation.
If you see [FAILED] Failed to start gdm.service during boot, your display manager configuration probably references a missing session or the NVIDIA module failed to load. Check the journal before guessing.
Convention aside: journalctl -xe reads better than journalctl alone. The x flag adds explanatory text and the e flag jumps to the end. Most sysadmins type journalctl -xeu <unit> muscle-memory style. Use it to trace GDM failures.
Run journalctl first. Read the actual error before guessing.
When to use this method versus alternatives
Use the NVIDIA .run installer when you need a bleeding-edge driver that has not reached the Fedora repositories yet. Use the akmod-nvidia package from RPM Fusion when you want automatic updates and kernel rebuilds handled by DNF. Use the kmod-nvidia package when you are on a stable kernel and do not want to compile modules on your machine. Use the open-source Nouveau driver when you only need basic display output and do not require hardware acceleration. Stay on the repository packages if you only deviate from the defaults occasionally.
Trust the package manager. Manual file edits drift, snapshots stay.