Posted on
• Artificial Intelligence

GPU Troubleshooting

Author
  • User
    linuxbash
    Posts by this author
    Posts by this author

GPU Troubleshooting on Linux: A Bash-First, No-Panic Guide

Ever hit a black screen after a kernel update, watched games crawl at 5 FPS, or saw your desktop compositor crash the moment you open a browser tab? GPU problems on Linux can be maddening—and also very fixable with a systematic approach and the right CLI tools.

This guide shows you how to quickly identify what’s wrong, install or repair drivers, read the right logs, and verify performance. You’ll get real commands you can paste into your terminal, with package installs for apt, dnf, and zypper.

Why GPU troubleshooting on Linux is different (and valid)

GPUs on Linux sit at the intersection of:

  • Kernel drivers (nvidia, amdgpu, i915), firmware, and sometimes DKMS/akmods

  • Mesa (OpenGL/Vulkan), vendor stacks (NVIDIA, ROCm/CUDA), and userland tools

  • Display servers (Wayland/Xorg), compositors, and hybrid graphics (laptops)

  • Sandboxed apps (Flatpak/Snap) that may not see the “right” GPU by default

That means small mismatches—like the wrong kernel module loaded or missing Vulkan ICD—can derail performance or stability. The good news: you can usually pinpoint the issue in minutes.

Install your toolbox (one-time)

Use the commands for your distro to install discovery, diagnostics, and test tools.

  • Debian/Ubuntu (apt):
sudo apt update && sudo apt install -y \
  pciutils lshw mesa-utils vulkan-tools glmark2 \
  nvtop radeontop intel-gpu-tools clinfo lm-sensors \
  linux-firmware dkms
  • Fedora (dnf):
sudo dnf install -y \
  pciutils lshw mesa-demos vulkan-tools glmark2 \
  nvtop radeontop intel-gpu-tools clinfo lm_sensors \
  linux-firmware
  • openSUSE (zypper):
sudo zypper install -y \
  pciutils lshw Mesa-demo-x vulkan-tools glmark2 \
  nvtop radeontop intel-gpu-tools clinfo lm_sensors \
  kernel-firmware

Tip: Some items may already be installed; that’s fine.

Step 1 — Inventory your GPU and the driver actually in use

Identify hardware and the kernel module bound to it:

lspci -k | grep -A3 -E "(VGA|3D)"

See which GPU OpenGL is using:

  • Debian/Ubuntu:
glxinfo -B
  • Fedora/openSUSE:
glxinfo -B   # provided by mesa-demos (Fedora) or Mesa-demo-x (openSUSE)

Check Vulkan visibility:

vulkaninfo | sed -n '1,120p'

Look at loaded modules:

lsmod | egrep "nvidia|amdgpu|i915|nouveau"

If you have NVIDIA:

nvidia-smi

If it errors, the NVIDIA kernel module or userland driver might not be installed/linked correctly.

Step 2 — Check logs and firmware

Boot/kernel logs often tell you exactly what failed:

journalctl -k -b | egrep -i "nvidia|amdgpu|i915|nouveau|drm|firmware|vulkan" | tail -n +1
dmesg | egrep -i "nvidia|amdgpu|i915|nouveau|drm|firmware" | tail -n +1

Update/confirm GPU firmware presence (already done if you ran the toolbox install):

  • Debian/Ubuntu:
sudo apt install -y linux-firmware
  • Fedora:
sudo dnf install -y linux-firmware
  • openSUSE:
sudo zypper install -y kernel-firmware

If you see “failed to load firmware …” messages for AMD/Intel in dmesg/journal, firmware is the first thing to fix.

Step 3 — Install or repair the right driver stack

A. NVIDIA (proprietary)

  • Debian/Ubuntu:
ubuntu-drivers devices
sudo ubuntu-drivers autoinstall
# or pin a specific branch:
# sudo apt install -y nvidia-driver-XXX  # e.g. nvidia-driver-550

Secure Boot warning: If Secure Boot is enabled, the driver may load unsigned and fail. See “Common fixes” below to sign/enroll or temporarily disable Secure Boot.

  • Fedora (RPM Fusion + akmods):
sudo dnf install -y \
  https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
  https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm

sudo dnf install -y akmod-nvidia xorg-x11-drv-nvidia-cuda
# Optional (often auto-pulled): kernel-devel kernel-headers
sudo reboot
# First boot may build the kernel module (akmod). Then verify:
nvidia-smi
  • openSUSE (official NVIDIA repo): For Tumbleweed:
sudo zypper ar -f https://download.nvidia.com/opensuse/tumbleweed/ nvidia
sudo zypper refresh
sudo zypper install -y nvidia-driver-G06
sudo reboot

For Leap 15.x (replace 15.5 with your version):

sudo zypper ar -f https://download.nvidia.com/opensuse/leap/15.5/ nvidia
sudo zypper refresh
sudo zypper install -y nvidia-driver-G06
sudo reboot

If the open-source Nouveau is still binding, blacklist it (see “Common fixes”).

B. AMD (open driver via amdgpu + Mesa)

The default open driver is usually the right choice. Ensure Vulkan userspace is present:

  • Debian/Ubuntu:
sudo apt install -y mesa-vulkan-drivers
# For Steam/32-bit games:
# sudo dpkg --add-architecture i386
# sudo apt update && sudo apt install -y mesa-vulkan-drivers:i386
  • Fedora:
sudo dnf install -y mesa-vulkan-drivers
  • openSUSE:
sudo zypper install -y Mesa-vulkan-drivers

If you require AMD’s proprietary OpenCL or ROCm, follow the vendor documentation for your distro; versions are sensitive to kernel, GPU generation, and distro release.

C. Intel (i915/i915-GPU + Mesa)

  • Debian/Ubuntu:
sudo apt install -y mesa-vulkan-drivers intel-gpu-tools
  • Fedora:
sudo dnf install -y mesa-vulkan-drivers intel-gpu-tools
  • openSUSE:
sudo zypper install -y Mesa-vulkan-drivers intel-gpu-tools

Step 4 — Monitor and test

A. Live usage, clocks, temps

  • All vendors:
nvtop              # works for NVIDIA/AMD/Intel on most distros
  • AMD:
radeontop          # GPU utilization by block
  • Intel:
intel_gpu_top
  • NVIDIA:
watch -n1 nvidia-smi
  • Temperatures (all):
sudo sensors-detect   # answer yes; one-time
watch -n1 sensors

B. Quick rendering sanity checks

  • OpenGL:
glxinfo -B
glxgears       # basic smoke test; not a benchmark
  • Vulkan:
vulkaninfo | less
  • Lightweight benchmark:
glmark2
  • OpenCL visibility:
clinfo | less

If vulkaninfo shows “No ICDs found,” your Vulkan userspace/ICD packages are missing.

Step 5 — Common fixes you’ll actually use

1) Secure Boot blocks NVIDIA module loading

  • Symptom: nvidia-smi fails, journal shows “nvidia: module verification failed”

  • Options:

    • Temporarily disable Secure Boot in firmware setup
    • Or sign the module and enroll a Machine Owner Key (MOK):
sudo apt install -y mokutil   # Debian/Ubuntu; on Fedora/openSUSE mokutil is usually present
openssl req -new -x509 -newkey rsa:2048 -keyout MOK.key -out MOK.crt -nodes -days 36500 -subj "/CN=Local NVIDIA Module/"
sudo mokutil --import MOK.crt
# Reboot, follow on-screen prompts to enroll key (choose the same password).
# After boot, rebuild/ensure the module is present:
sudo dkms status || true
nvidia-smi

2) Kernel updated, driver didn’t

  • On Debian/Ubuntu DKMS:
sudo dkms status
sudo dkms autoinstall
journalctl -k -b | tail -n 200
  • On Fedora akmods:
sudo akmods --force
sudo journalctl -k -b | egrep -i "akmod|nvidia" | tail -n +1

3) Blacklist Nouveau when using proprietary NVIDIA

  • Create blacklist and rebuild initramfs:
echo "blacklist nouveau" | sudo tee /etc/modprobe.d/blacklist-nouveau.conf
echo "options nouveau modeset=0" | sudo tee -a /etc/modprobe.d/blacklist-nouveau.conf
# Debian/Ubuntu:
sudo update-initramfs -u
# Fedora/openSUSE:
sudo dracut --force
sudo reboot

4) Hybrid graphics (laptops) using the wrong GPU

  • AMD/Intel iGPU offload to dGPU (DRI_PRIME):
DRI_PRIME=1 glxinfo -B
DRI_PRIME=1 glmark2
  • NVIDIA PRIME Render Offload:
__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia glxinfo -B
__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia glmark2

Persisting per-app can be done via wrappers or desktop launchers using these env vars.

5) Wayland vs Xorg compositor quirks

  • If you suspect Wayland/compositor issues, try an Xorg session from the login screen.

  • To force GDM to offer Xorg (Debian/Ubuntu/Fedora/openSUSE with GDM):

sudo sed -i 's/^#WaylandEnable=false/WaylandEnable=false/' /etc/gdm/custom.conf
sudo systemctl restart gdm

Note: Restarting display manager logs you out.

Real-world quick wins

  • After a kernel update, black screen on NVIDIA:

    • Boot to an older kernel from GRUB, install/rebuild akmod/dkms, check Secure Boot, then reboot.

  • Games on Steam perform poorly on AMD/Intel:

    • Ensure Vulkan is present:
    • Debian/Ubuntu: sudo apt install mesa-vulkan-drivers mesa-vulkan-drivers:i386
    • Fedora: sudo dnf install mesa-vulkan-drivers
    • openSUSE: sudo zypper install Mesa-vulkan-drivers

  • Laptop uses iGPU instead of dGPU:

    • Launch game with DRI_PRIME=1 (AMD/Intel) or NVIDIA offload env vars shown above.

  • Flatpak app can’t see GPU/Vulkan:

    • Install Flatpak runtimes that include Vulkan and enable permissions, or run natively for testing.

Conclusion and next steps

With the right toolkit and a few focused checks, most Linux GPU issues boil down to:

  • Is the right kernel module bound?

  • Do we have the correct userspace (Mesa/NVIDIA/Vulkan/OpenCL)?

  • Are logs clear of firmware/verification errors?

  • Are we launching apps on the intended GPU?

Bookmark this guide, and the next time your desktop tears, stutters, or goes blank, run Steps 1–4, then apply the Common fixes. If you’re still stuck, paste the outputs of lspci -k, glxinfo -B, vulkaninfo (head), and relevant journalctl lines into your support post—those four snippets solve most mysteries fast.

Want a tailored checklist for your exact distro and GPU? Tell me your:

  • Distro/version

  • GPU model

  • Output of: lspci -k | grep -A3 -E "(VGA|3D)" and glxinfo -B

I’ll generate a minimal, copy-paste plan for your system.

Related posts