Make Hyprland use the right GPU with AQ_DRM_DEVICES
Checked on this omarchy 4.0.2-1 workstation (Hyprland 0.56.2, kernel 7.1.9-arch1-2) and against both cited wiki pages fetched in full. The cause holds and is left alone: the upstream Multi-GPU page (fetched as content/configuring/extra/multi-gpu.md from hyprwm/hyprland-wiki) says the cardN symlink is dynamically assigned at boot and unsuitable as a GPU marker, and says a card driving a monitor must appear in AQ_DRM_DEVICES even when it is not the primary renderer. Confirmed on this machine that cardN numbering is not even dense: one RTX 3090 at 01:00.0 is card1 and there is no card0.
The fix was wrong for Omarchy 4 in the way the brief predicts. It wrote env = AQ_DRM_DEVICES,... into ~/.config/hypr/envs.conf, which is hyprlang syntax in a file nothing reads. Confirmed here: ~/.config/hypr/hyprland.lua requires only hypr.monitors, hypr.input, hypr.bindings, hypr.looknfeel and hypr.autostart, and grep -rn 'hypr.envs' /usr/share/omarchy ~/.config/hypr returns exactly one hit, default.hypr.envs at /usr/share/omarchy/default/hypr/omarchy.lua:16, so ~/.config/hypr/envs.lua is dead too. The record already carried an hl.env line but offered it as a "Hyprland 0.55+" afterthought rather than the Omarchy 4 path, and gave no placement rule. Rewrote the fix to lead with hl.env in ~/.config/hypr/hyprland.lua below require("default.hypr.omarchy"), and kept the hyprlang form labelled as Hyprland 0.54 and older on plain Arch.
Two source URLs are dead and are removed. https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/Configuring/Advanced%20and%20Cool/Multi-GPU.md returns 404: the page moved to content/configuring/extra/multi-gpu.md, canonical https://wiki.hypr.land/configuring/extra/multi-gpu/. https://github.com/basecamp/omarchy/issues/1776 returns 404 over HTTP even though https://github.com/basecamp/omarchy itself redirects to omacom/omarchy: the rename redirect does not carry issue paths, so https://github.com/omacom/omarchy/issues/1776 replaces it. Read issue 1776 in full. It is a hybrid-GPU power-management request and it does support the udev symlink recipe and the AQ_DRM_DEVICES list, though its own instructions put the export in ~/.config/uwsm/env and in ~/.config/hypr/hyprland.conf, both of which are Omarchy 3 era advice.
Corrected the uwsm branch rather than deleting it. The record named ~/.config/uwsm/env-hyprland, which /usr/share/doc/uwsm/README.md (uwsm 0.26.7-1) does list, but Omarchy 4's default session is /usr/share/wayland-sessions/hyprland.desktop with Exec=/usr/bin/start-hyprland and no uwsm, and the uwsm-managed entry is a separate hyprland-uwsm.desktop. Confirmed the running compositor here is Hyprland --watchdog-fd 4 with no uwsm in the process tree. Omarchy's own /usr/share/uwsm/env.d/10-omarchy points users at ~/.config/uwsm/env.d/*, so that is what the fix now shows.
Corrected verify. nvidia-smi showing no processes is not a usable test on Omarchy 4, because /usr/share/omarchy/default/hypr/nvidia.lua sets LIBVA_DRIVER_NAME=nvidia on Turing and newer and that alone keeps browsers holding /dev/nvidia-uvm. Replaced it with reading the compositor's own DRM file descriptors, confirmed working here as an unprivileged user: ls -l /proc/$(pgrep -x Hyprland | head -1)/fd shows three card1 handles and four renderD128. Also noted where the line falls against the neighbouring record: nvidia-env-forced-on-igpu-primary-hybrid-laptop owns the LIBVA_DRIVER_NAME and __GLX_VENDOR_LIBRARY_NAME pin that Omarchy forces on hybrid laptops, this record owns which DRM device the compositor renders and scans out on. They are adjacent and not duplicates.
Corrected danger. The original advised testing by running Hyprland from Ctrl+Alt+F2 and pressing Ctrl+C, which does not work on Omarchy: a second Hyprland reads the same ~/.config/hypr/hyprland.lua, tries to start a full second Omarchy session, and cannot take DRM master while the first compositor holds it. Kept the real risk, which is a next login with no output, added that hyprctl reload neither tests nor undoes the change because aquamarine reads the variable once at backend creation, and made the TTY the recovery route rather than the test route. Left severity high and frequency common alone.
Not exercised: this is a single-GPU NVIDIA desktop with one card at 01:00.0, so no multi-GPU selection, no udev symlink, no AQ_FORCE_LINEAR_BLIT and no iGPU-primary path could be tried here. AQ_DRM_DEVICES is unset in this session. Nothing on this machine was modified and no hyprctl command other than read-only version, monitors and the process inspection above was run. The ordering claim that an hl.env below require("default.hypr.omarchy") wins is taken from the shipped comment in ~/.config/hypr/hyprland.lua and from the neighbouring record's own audit, not re-tested here.
If the list names only a GPU that drives no monitor, or a symlink that does not exist, Hyprland starts with no visible output and your next login is a black screen. Aquamarine reads the variable only when it creates the DRM backend, so hyprctl reload cannot test it and cannot undo it either.
Check every path resolves before you log out:
ls -l /dev/dri/intel-igpu /dev/dri/nvidia-dgpu
Make sure you can reach a text console with Ctrl + Alt + F2 first, so a bad list costs one line deleted from ~/.config/hypr/hyprland.lua rather than a rebuild. On Omarchy 4 there is no second desktop session to fall back into.
Do not try to test it by running a second Hyprland from the console. On Omarchy that reads the same ~/.config/hypr/hyprland.lua and tries to start a whole second Omarchy session, and it cannot take DRM master while the first compositor holds it, so the run tells you nothing about the variable.
Symptom
On a multi-GPU machine Hyprland either picks the wrong renderer (dGPU pegged and hot on a laptop, or the compositor is unusably laggy), or a monitor plugged into the second GPU shows nothing at all and is missing from hyprctl monitors.
Cause
Hyprland's aquamarine backend picks a DRM device on its own. /dev/dri/card0 and card1 are assigned at boot and can swap between reboots, so whichever card is enumerated first wins. Any GPU that drives a monitor must be in the device list, even if it is not the primary renderer.
Fix
Identify the cards by PCI address, not by cardN. The cardN numbers are handed out at boot and are not even predictable on a single-GPU machine. This workstation has one RTX 3090 and its node is card1, with no card0 present at all.
lspci -d ::03xx
ls -l /dev/dri/by-path
Create a stable symlink for each card with udev. The example is for an Intel iGPU. Repeat it with AMD or NVIDIA and a different symlink name for the other card:
IGPU_ID=$(lspci -d ::03xx | grep 'Intel' | cut -f1 -d' ')
sudo tee /etc/udev/rules.d/90-intel-igpu-dev-path.rules >/dev/null <<EOF
KERNEL=="card*", KERNELS=="0000:$IGPU_ID", SUBSYSTEM=="drm", SUBSYSTEMS=="pci", SYMLINK+="dri/intel-igpu"
EOF
sudo udevadm control --reload
sudo udevadm trigger
ls -l /dev/dri/intel-igpu
Then give Hyprland the priority order. The first entry is the primary renderer and the list is :-separated.
**Omarchy 4.** Put the line in ~/.config/hypr/hyprland.lua, below the require("default.hypr.omarchy") line, so it loads after Omarchy's defaults:
-- ~/.config/hypr/hyprland.lua, below require("default.hypr.omarchy")
hl.env("AQ_DRM_DEVICES", "/dev/dri/intel-igpu:/dev/dri/nvidia-dgpu")
Do not use ~/.config/hypr/envs.conf or ~/.config/hypr/envs.lua. Omarchy 4 reads neither. The shipped ~/.config/hypr/hyprland.lua requires only hypr.monitors, hypr.input, hypr.bindings, hypr.looknfeel and hypr.autostart, nothing in /usr/share/omarchy requires hypr.envs, and the only envs module in the tree is default.hypr.envs, required at /usr/share/omarchy/default/hypr/omarchy.lua:16. A file at either of those paths is simply never read.
**Plain Arch on Hyprland 0.55 or newer**, which also uses Lua. The same call, in whichever file your hyprland.lua loads:
hl.env("AQ_DRM_DEVICES", "/dev/dri/intel-igpu:/dev/dri/nvidia-dgpu")
**Plain Arch on Hyprland 0.54 or older**, which still uses hyprlang:
env = AQ_DRM_DEVICES,/dev/dri/intel-igpu:/dev/dri/nvidia-dgpu
**If you log in through a uwsm-managed session** you can export the variable before the compositor starts instead. Omarchy 4 ships both session entries, /usr/share/wayland-sessions/hyprland.desktop (Exec=/usr/bin/start-hyprland, no uwsm) and /usr/share/wayland-sessions/hyprland-uwsm.desktop, and the default is the plain one, so check which you are on before bothering:
pgrep -a uwsm
If you are on the uwsm session, Omarchy's own /usr/share/uwsm/env.d/10-omarchy points at the env.d directory:
# ~/.config/uwsm/env.d/gpu
export AQ_DRM_DEVICES="/dev/dri/intel-igpu:/dev/dri/nvidia-dgpu"
uwsm also reads ~/.config/uwsm/env and ~/.config/uwsm/env-hyprland, per /usr/share/doc/uwsm/README.md.
If a secondary monitor on the NVIDIA card is still broken or laggy, add:
hl.env("AQ_FORCE_LINEAR_BLIT", "0")
Log out and back in. hyprctl reload is not enough. Aquamarine reads AQ_DRM_DEVICES once, when it creates the DRM backend at compositor start, so a reload re-parses the config without re-picking the device.
Verify
Check which DRM nodes the compositor actually opened, and which vendor owns them:
ls -l /proc/$(pgrep -x Hyprland | head -1)/fd | grep -oE 'card[0-9]+|renderD[0-9]+' | sort | uniq -c
for n in /sys/class/drm/renderD*; do
printf '%s %s vendor=%s\n' "$(basename "$n")" "$(basename "$(readlink -f "$n/device")")" "$(cat "$n/device/vendor")"
done
Vendor 0x8086 is Intel, 0x1002 is AMD, 0x10de is NVIDIA. The node Hyprland holds should be the one you named first.
hyprctl monitors # every connected display is listed
env | grep AQ_DRM_DEVICES # your list, in a terminal Hyprland spawned
Do not use nvidia-smi showing no processes as the test. On Omarchy 4 /usr/share/omarchy/default/hypr/nvidia.lua sets LIBVA_DRIVER_NAME=nvidia on Turing and newer cards, which keeps browsers holding /dev/nvidia-uvm open for reasons that have nothing to do with AQ_DRM_DEVICES. That is the subject of nvidia-env-forced-on-igpu-primary-hybrid-laptop.