Choose and check a graphics driver

Synopsis #

Desktop graphics depend first on a kernel driver for the actual GPU. Xorg, a Wayland compositor, and a desktop environment are later layers. Installing several display drivers or generating a large Xorg configuration before the kernel driver works makes failures harder to isolate.

This guide identifies the GPU, selects the driver family, and verifies kernel attachment. It does not promise that every GPU generation or hybrid-graphics arrangement works with one recipe. Complete the hardware preflight first when an installation decision depends on graphics support.

Identify every GPU #

List PCI display controllers:

$ pciconf -lv | grep -B3 display

Record the vendor, device description, and numeric identifiers. A laptop may contain an integrated GPU and a discrete GPU. Determine which controller drives the internal display before disabling a device or configuring PRIME offload.

Check whether the machine booted through UEFI or BIOS on platforms that expose this sysctl:

$ sysctl machdep.bootmethod

This matters when falling back to a system-console framebuffer: the FreeBSD Handbook directs UEFI systems to SCFB and BIOS systems to VESA. Those fallback drivers do not provide the same acceleration or Wayland capabilities as a maintained KMS driver.

Select one driver family #

Use the current FreeBSD graphics chapter and the device generation to choose the package and module:

Do not infer an AMD or NVIDIA legacy package from the card’s age alone. Support tables change, and a package that installs successfully can still be the wrong driver for the device.

Install and enable the selected module #

For a supported Intel GPU, the current documented package and startup setting are:

# pkg install drm-kmod
# sysrc kld_list+=i915kms

For a supported current-generation AMD GPU whose support table specifies amdgpu:

# pkg install drm-kmod
# sysrc kld_list+=amdgpu

For an NVIDIA GPU confirmed to use the current DRM package:

# pkg install nvidia-drm-kmod
# sysrc kld_list+=nvidia-drm

The current FreeBSD procedure also enables kernel modesetting for this module in /boot/loader.conf:

hw.nvidiadrm.modeset="1"

PRIME and Wayland require that KMS path. Older NVIDIA driver generations use different modules and do not accept this line as a substitute for selecting the correct versioned package.

These are alternatives, not a combined block. A hybrid system may need more deliberate configuration than loading all three. Follow the current official procedure for that layout.

Reboot after enabling the selected module. Loading a graphics module into an active console can be useful during diagnosis, but a clean boot gives better evidence about startup order and firmware loading.

Verify kernel attachment before starting a desktop #

After reboot, confirm the release, loaded modules, DRM nodes, and boot messages:

$ freebsd-version -kru
$ kldstat
$ ls -l /dev/dri
$ dmesg | grep -Ei 'drm|i915|amdgpu|radeon|nvidia|vgapci|firmware'

The expected module names depend on the selected driver. Modern DRM operation normally creates nodes beneath /dev/dri. An empty or absent directory, a firmware error, or a driver attach failure should be resolved before installing multiple desktop environments.

Confirm that the login belongs to the video group when the selected display stack requires direct device access:

$ id

Add the login if needed, substituting its real name, then start a new login session:

# pw groupmod video -m loginname

Existing sessions do not acquire new supplementary groups automatically.

Diagnose one layer at a time #

Use this order when the screen remains blank or a graphical session exits:

1. Confirm that pciconf reports the expected GPU and driver attachment.
2. Confirm that the intended kernel module loaded and created the expected device nodes.
3. Read the boot messages for missing firmware, unsupported device identifiers, and attach failures.
4. Confirm video group membership in a fresh login session.
5. Start a minimal display stack from a virtual terminal and save its complete error output.
6. Add a display manager only after a manual session starts reliably.

For Xorg, inspect both /var/log/Xorg.0.log and $HOME/.local/share/xorg/Xorg.0.log; the location depends on how the server was started. Lines marked (EE) are errors, while (WW) lines need to be correlated with the actual failure.

For Wayland, collect the compositor’s terminal output or its documented log. A compositor failure is not automatically a kernel-driver failure. The Xorg or Wayland decision guide describes the different boundaries.

Avoid premature configuration #

Modern Xorg normally discovers the KMS device without a generated /etc/X11/xorg.conf. Create a small file under /usr/local/etc/X11/xorg.conf.d/ only when the Xorg log and official driver documentation identify a specific ambiguity.

Do not make graphics power tunables, experimental PRIME settings, or device hints the first response to a blank screen. They can hide the original failure and create a boot-time dependency. Establish the default driver path first, then make one measured change at a time.

After the driver works, continue with a maintainable desktop baseline . Laptop installations should also complete the suspend and Wi-Fi preflight before enabling lid-triggered suspend.

Primary references #

• FreeBSD Handbook: Graphics drivers
• FreeBSD Handbook: Xorg configuration
• FreeBSD Handbook: Wayland
• FreeBSD AMD graphics support matrix
• pciconf(8)
• kldstat(8)
• sysrc(8)
• Xorg(1)