hyprland - SKILL.md Agent Skill

name: hyprland description: Hyprland Wayland compositor on NixOS. This skill should be used when configuring programs.hyprland, GPU rendering (Intel/AMD/NVIDIA), Wails/webkit2gtk fixes, xdg portals, home-manager, or wallpapers.

Hyprland on NixOS

Overview

Configure Hyprland (dynamic tiling Wayland compositor) on NixOS. Optimized for running webkit2gtk-based desktop apps (Wails, Tauri) on integrated graphics. Covers both nixpkgs and flake-input install paths.

Quick Reference

Task	Where
NixOS module options	`references/nixos-module.md`
Flake input + cachix setup	`references/flake-setup.md`
Integrated graphics (Intel/AMD)	`references/integrated-graphics.md`
Multi-GPU (Intel/AMD/NVIDIA) smart defaults	`references/multi-gpu.md`
Multi-GPU unified module (`mySystem.gpu`)	`references/multi-gpu-module.md`
Per-vendor Hyprland env var matrix	`references/multi-gpu-env-vars.md`
Wails blank-screen webkit2gtk fix	`references/wails-webkit-fixes.md`
Animated wallpapers (mpvpaper, awww, gtk-layer-shell)	`references/animated-wallpapers.md`
home-manager hyprland module	`references/home-manager.md`
Sample `hyprland.conf`	`references/hyprland-conf.md`
Complete `flake.nix` example	`references/flake-example.md`
Ecosystem packages (hypr*, waybar)	`references/ecosystem-packages.md`
Validation commands + common traps	`references/validation.md`

For NixOS-level concerns (flakes, modules, packaging, devShells, home-manager), see the sibling nixos skill: ~/.claude/skills/nixos/. Cross-references: flakes.md, nixos-modules.md, home-manager.md, packaging.md, devshells.md.

Core Setup

Two install paths — pick one:

A. Pure nixpkgs (simpler, slightly older):

programs.hyprland = {
  enable = true;
  xwayland.enable = true;
  withUWSM = true;  # 25.11+ systemd-managed session
};
xdg.portal.extraPortals = [ pkgs.xdg-desktop-portal-gtk ];

B. Hyprland flake input (recommended, newest):

inputs.hyprland.url = "github:hyprwm/Hyprland";
# DO NOT set inputs.hyprland.inputs.nixpkgs.follows — breaks cachix

Then import hyprland.nixosModules.default and override programs.hyprland.package = inputs.hyprland.packages.${system}.hyprland;. See references/flake-setup.md.

Critical Wails / webkit2gtk Fix

Wails apps show a blank window on Hyprland + integrated graphics. Fix by setting these env vars (system-wide, in hyprland.conf, or in Go code):

environment.sessionVariables = {
  WEBKIT_DISABLE_DMABUF_RENDERER = "1";   # primary fix
  WEBKIT_DISABLE_COMPOSITING_MODE = "1";  # secondary fix
  GDK_BACKEND     = "wayland,x11";
  NIXOS_OZONE_WL  = "1";
  QT_QPA_PLATFORM = "wayland;xcb";
};

Build Wails apps with wails build -tags webkit2_41 (NixOS ships webkitgtk_4_1, not 4.0). Full env list and per-app fallback in references/wails-webkit-fixes.md.

Integrated Graphics (24.11+)

hardware.opengl.* was renamed to hardware.graphics.* in NixOS 24.11.

hardware.graphics = {
  enable = true;
  enable32Bit = true;
  extraPackages = with pkgs; [
    intel-media-driver  # Intel Broadwell+ (iHD)
    intel-vaapi-driver  # older Intel (i965)
    vpl-gpu-rt          # 12th gen / Arc oneVPL
    libvdpau-va-gl      # VDPAU shim
  ];
};

For AMD APU: mesa RADV is built in — only add rocmPackages.clr.icd for OpenCL. Avoid mixing amdvlk with RADV. See references/integrated-graphics.md.

Multi-GPU & NVIDIA (2025/2026)

For configs that handle Intel/AMD/NVIDIA from one module, use nixos-hardware + a mySystem.gpu.vendor enum option. Modern NVIDIA on Hyprland is much simpler than older guides:

Drop these obsolete settings from any older config: --unsupported-gpu, cursor:no_hardware_cursors, render:explicit_sync, WLR_NO_HARDWARE_CURSORS. Driver 555+ negotiates explicit sync via syncobj automatically.
hardware.nvidia.open has no default for driver ≥ 560 — set explicitly. NVIDIA 50xx-series requires open = true.
PRIME sync/reverseSync are X11-only — Wayland MUST use prime.offload.
NVIDIA env vars shrunk to two: LIBVA_DRIVER_NAME=nvidia and __GLX_VENDOR_LIBRARY_NAME=nvidia.

inputs.nixos-hardware.url = "github:NixOS/nixos-hardware/master";
modules = [ inputs.nixos-hardware.nixosModules.common-gpu-nvidia-prime ];

See references/multi-gpu.md for the full smart-defaults pattern, multi-gpu-module.md for a paste-ready unified module, and multi-gpu-env-vars.md for the env var matrix.

Animated Wallpapers

Hyprpaper is static-only. For animated/video wallpapers and Wails-controlled wallpaper apps:

Tool	NixOS attr	Use
`mpvpaper`	`pkgs.mpvpaper`	Video (mp4/webm), hwdec, mpv IPC socket
`awww` (was `swww`)	`pkgs.awww`	Animated GIF/WebP/APNG, transitions
`linux-wallpaperengine`	`pkgs.linux-wallpaperengine`	Steam Workshop wallpapers
`gtk-layer-shell`	`pkgs.gtk-layer-shell`	Library to make a Wails GTK3 window a wallpaper layer

Note: pkgs.swww was removed in nixpkgs PR #459649 (March 2026) — use pkgs.awww. Compat shims preserve swww/swww-daemon commands.

Recommended Wails pattern: app launches mpvpaper and controls it via /tmp/mpv-socket JSON IPC. Advanced: patch Wails internals to call gtk-layer-shell on the GtkWindow via github.com/diamondburned/gotk4-layer-shell. See references/animated-wallpapers.md for both paths plus the wlr-layer-shell protocol details.

XDG Portal

programs.hyprland.enable already wires xdg-desktop-portal-hyprland. Add the GTK portal for file pickers in Wails apps:

xdg.portal = {
  enable = true;
  extraPortals = [ pkgs.xdg-desktop-portal-gtk ];
};

Cachix (avoid hours of compile)

nix.settings = {
  substituters = [ "https://cache.nixos.org" "https://hyprland.cachix.org" ];
  trusted-public-keys = [
    "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
    "hyprland.cachix.org-1:a7pgxzMz7+chwVL3/pzj6jIBMioiJM7ypFP8PwtkuGc="
  ];
};

Validation & Common Traps

See references/validation.md for validation commands and common traps.