Hyprland Documentation
Complete reference for the Hyprland Wayland compositor, auto-generated from the official wiki at https://wiki.hypr.land/.
The references/ directory contains the full, unmodified wiki markdown from https://github.com/hyprwm/hyprland-wiki, updated daily.
How to Use
- Identify the topic from the user's question and read the matching reference file from the tables below.
- Base answers on those files. If more detail is needed, fetch the latest docs from the raw GitHub URLs in Live Fetching.
- Since Hyprland 0.55, the config is Lua (
~/.config/hypr/hyprland.lua): hl.config({...}), hl.bind(...), hl.monitor({...}), hl.window_rule({...}), hl.on(...). The old hyprlang format (hyprland.conf) is deprecated. Check the user's version with hyprctl version when in doubt.
- For Hyprland 0.54 and earlier, use hyprlang syntax and point the user to the versioned wiki at https://wiki.hypr.land/0.54.0/ (the reference files here track the current Lua docs).
- Split configs use Lua
require("subdir/file"), not the old source = keyword.
- For NixOS users, note that
hyprpm is unsupported on Nix — use Home Manager or the NixOS module for plugins.
- For troubleshooting, check
references/faq.md first.
Reference Files
Configuration
| Topic |
File |
| Config file basics, Lua syntax, require, LSP stubs |
references/start.md |
| Variables / options (general, decoration, input, misc, etc.) |
references/variables.md |
| Keybinds (hl.bind, flags, submaps) |
references/binds.md |
| Dispatchers (hl.dsp.*, hl.dispatch) |
references/dispatchers.md |
| Window rules and layer rules |
references/window-rules.md |
| Monitor configuration |
references/monitors.md |
| Autostart (hyprland.start event) |
references/autostart.md |
| Animations and bezier curves |
references/animations.md |
| Workspace rules and smart gaps |
references/workspace-rules.md |
| Environment variables |
references/environment-variables.md |
| Layouts (dwindle, master, scrolling, monocle, custom) |
references/layouts.md |
| Lua scripting, events, timers (hl.on, hl.exec_cmd) |
references/lua-scripting.md |
| Per-device input config |
references/devices.md |
| Notifications API |
references/notifications.md |
| Performance tuning |
references/performance.md |
| XWayland |
references/xwayland.md |
| Screen tearing |
references/tearing.md |
| Multi-GPU |
references/multi-gpu.md |
| Virtual GPU |
references/virtual-gpu.md |
| Permissions |
references/permissions.md |
| Gestures |
references/gestures.md |
| Systemd integration (graphical-session.target) |
references/systemd.md |
| Naming conventions (workspace, monitor, window selectors) |
references/naming-conventions.md |
| Lua code snippets and example configs |
references/code-snippets.md |
Tools
| Topic |
File |
| hyprctl CLI usage (eval, repl, batch) |
references/hyprctl.md |
| IPC sockets and events |
references/ipc.md |
Hypr Ecosystem
| Topic |
File |
| Hyprlock (screen lock) |
references/hyprlock.md |
| Hypridle (idle management) |
references/hypridle.md |
| Hyprpaper (wallpaper) |
references/hyprpaper.md |
| Hyprlauncher (app launcher) |
references/hyprlauncher.md |
| Hyprpicker (color picker) |
references/hyprpicker.md |
| Hyprsunset (blue light filter) |
references/hyprsunset.md |
| Hyprcursor (cursor themes) |
references/hyprcursor.md |
| XDPH (xdg-desktop-portal-hyprland) |
references/xdph.md |
| Hyprpolkitagent (polkit auth) |
references/hyprpolkitagent.md |
| Hyprshutdown (shutdown utility) |
references/hyprshutdown.md |
| Hyprsysteminfo (system info) |
references/hyprsysteminfo.md |
| Hyprpwcenter (power management) |
references/hyprpwcenter.md |
| Hyprland Qt support |
references/hyprland-qt-support.md |
| Dev libraries (hyprtoolkit, hyprlang, hyprutils, aquamarine, etc.) |
references/hypr-libraries.md |
Plugins
| Topic |
File |
| Plugin usage and development |
references/plugins.md |
Platform-Specific
| Topic |
File |
| NixOS / Nix / Home Manager |
references/nix.md |
| Nvidia setup |
references/nvidia.md |
Help
| Topic |
File |
| FAQ and troubleshooting |
references/faq.md |
| Getting started / installation |
references/getting-started.md |
| Useful utilities (bars, launchers, screenshots, systemd, etc.) |
references/useful-utilities.md |
| Crashes and bugs |
references/crashes-and-bugs.md |
| Contributing to Hyprland |
references/contributing.md |
Live Fetching
When reference files are insufficient, fetch the latest docs from raw GitHub:
https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/<section>/<page>.md
Paths are lowercase. Section index pages are _index.md. Examples:
https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/configuring/core/config-options.mdhttps://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/configuring/core/advanced-configuration/using-hyprctl.mdhttps://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/hypr-ecosystem/user/hyprlock.mdhttps://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/nix/installing-hyprland-on-nixos.md
The <!-- source: ... --> header at the top of each reference file gives the matching wiki section.
Quick Reference (Hyprland 0.55+, Lua config)
Config file location
~/.config/hypr/hyprland.lua (or $XDG_CONFIG_HOME/hypr/hyprland.lua, override with Hyprland --config)
Options
hl.config({
general = {
border_size = 2,
gaps_in = 5,
},
})
Multiple hl.config() calls are allowed; each updates only what it receives.
Binds
hl.bind("SUPER + SHIFT + Q", hl.dsp.exec_cmd("firefox"))
hl.bind("SUPER + X", function()
hl.dispatch(hl.dsp.window.float({ action = "toggle" }))
end)
Autostart
hl.on("hyprland.start", function()
hl.exec_cmd("waybar & hyprpaper")
end)
Window rules
hl.window_rule({
match = { class = "firefox" },
opacity = 0.9,
float = true,
})
Monitors
hl.monitor({
output = "DP-1",
mode = "1920x1080@144",
position = "0x0",
scale = 1,
})
Split config
require("conf/binds") -- ~/.config/hypr/conf/binds.lua
hyprctl runtime control
hyprctl reload
hyprctl eval 'hl.config({ general = { border_size = 3 } })'
hyprctl repl # interactive Lua REPL
hyprctl --batch "..."
Legacy (Hyprland 0.54 and earlier, hyprlang)
Old-style ~/.config/hypr/hyprland.conf:
bind = MODS, key, dispatcher, params
general {
border_size = 2
}
monitor = name, resolution@rate, position, scale
Full legacy docs: https://wiki.hypr.land/0.54.0/
1---2name: hyprland3description: This skill should be used when the user asks about "Hyprland configuration", "hyprland.lua", "hyprland.conf", "Hyprland Lua config", "hyprctl", "Hyprland keybinds", "Hyprland window rules", "Hyprland monitors", "Hyprland dispatchers", "Hyprland animations", "Hyprland workspaces", "Hyprland IPC", "Hyprland plugins", "hyprlock", "hypridle", "hyprpaper", "hyprcursor", "hyprpicker", "hyprsunset", "xdg-desktop-portal-hyprland", "Hyprland on NixOS", "Hyprland Home Manager", "Hyprland layouts", "Hyprland dwindle", "Hyprland master layout", "Hyprland FAQ", "Hyprland performance", "Hyprland Nvidia", "Hyprland screen sharing", "Hyprland special workspace", "Hyprland smart gaps", "Hyprland multi-monitor", "Hyprland tearing", or any topic related to configuring, troubleshooting, or extending the Hyprland Wayland compositor and its ecosystem tools.4---56# Hyprland Documentation78Complete reference for the Hyprland Wayland compositor, auto-generated from the official wiki at https://wiki.hypr.land/.910The `references/` directory contains the full, unmodified wiki markdown from https://github.com/hyprwm/hyprland-wiki, updated daily.1112## How to Use13141. Identify the topic from the user's question and read the matching reference file from the tables below.152. Base answers on those files. If more detail is needed, fetch the latest docs from the raw GitHub URLs in Live Fetching.163. **Since Hyprland 0.55, the config is Lua** (`~/.config/hypr/hyprland.lua`): `hl.config({...})`, `hl.bind(...)`, `hl.monitor({...})`, `hl.window_rule({...})`, `hl.on(...)`. The old hyprlang format (`hyprland.conf`) is deprecated. Check the user's version with `hyprctl version` when in doubt.174. For Hyprland 0.54 and earlier, use hyprlang syntax and point the user to the versioned wiki at https://wiki.hypr.land/0.54.0/ (the reference files here track the current Lua docs).185. Split configs use Lua `require("subdir/file")`, not the old `source =` keyword.196. For NixOS users, note that `hyprpm` is unsupported on Nix — use Home Manager or the NixOS module for plugins.207. For troubleshooting, check `references/faq.md` first.2122## Reference Files2324### Configuration2526| Topic | File |27|-------|------|28| Config file basics, Lua syntax, require, LSP stubs | **`references/start.md`** |29| Variables / options (general, decoration, input, misc, etc.) | **`references/variables.md`** |30| Keybinds (hl.bind, flags, submaps) | **`references/binds.md`** |31| Dispatchers (hl.dsp.*, hl.dispatch) | **`references/dispatchers.md`** |32| Window rules and layer rules | **`references/window-rules.md`** |33| Monitor configuration | **`references/monitors.md`** |34| Autostart (hyprland.start event) | **`references/autostart.md`** |35| Animations and bezier curves | **`references/animations.md`** |36| Workspace rules and smart gaps | **`references/workspace-rules.md`** |37| Environment variables | **`references/environment-variables.md`** |38| Layouts (dwindle, master, scrolling, monocle, custom) | **`references/layouts.md`** |39| Lua scripting, events, timers (hl.on, hl.exec_cmd) | **`references/lua-scripting.md`** |40| Per-device input config | **`references/devices.md`** |41| Notifications API | **`references/notifications.md`** |42| Performance tuning | **`references/performance.md`** |43| XWayland | **`references/xwayland.md`** |44| Screen tearing | **`references/tearing.md`** |45| Multi-GPU | **`references/multi-gpu.md`** |46| Virtual GPU | **`references/virtual-gpu.md`** |47| Permissions | **`references/permissions.md`** |48| Gestures | **`references/gestures.md`** |49| Systemd integration (graphical-session.target) | **`references/systemd.md`** |50| Naming conventions (workspace, monitor, window selectors) | **`references/naming-conventions.md`** |51| Lua code snippets and example configs | **`references/code-snippets.md`** |5253### Tools5455| Topic | File |56|-------|------|57| hyprctl CLI usage (eval, repl, batch) | **`references/hyprctl.md`** |58| IPC sockets and events | **`references/ipc.md`** |5960### Hypr Ecosystem6162| Topic | File |63|-------|------|64| Hyprlock (screen lock) | **`references/hyprlock.md`** |65| Hypridle (idle management) | **`references/hypridle.md`** |66| Hyprpaper (wallpaper) | **`references/hyprpaper.md`** |67| Hyprlauncher (app launcher) | **`references/hyprlauncher.md`** |68| Hyprpicker (color picker) | **`references/hyprpicker.md`** |69| Hyprsunset (blue light filter) | **`references/hyprsunset.md`** |70| Hyprcursor (cursor themes) | **`references/hyprcursor.md`** |71| XDPH (xdg-desktop-portal-hyprland) | **`references/xdph.md`** |72| Hyprpolkitagent (polkit auth) | **`references/hyprpolkitagent.md`** |73| Hyprshutdown (shutdown utility) | **`references/hyprshutdown.md`** |74| Hyprsysteminfo (system info) | **`references/hyprsysteminfo.md`** |75| Hyprpwcenter (power management) | **`references/hyprpwcenter.md`** |76| Hyprland Qt support | **`references/hyprland-qt-support.md`** |77| Dev libraries (hyprtoolkit, hyprlang, hyprutils, aquamarine, etc.) | **`references/hypr-libraries.md`** |7879### Plugins8081| Topic | File |82|-------|------|83| Plugin usage and development | **`references/plugins.md`** |8485### Platform-Specific8687| Topic | File |88|-------|------|89| NixOS / Nix / Home Manager | **`references/nix.md`** |90| Nvidia setup | **`references/nvidia.md`** |9192### Help9394| Topic | File |95|-------|------|96| FAQ and troubleshooting | **`references/faq.md`** |97| Getting started / installation | **`references/getting-started.md`** |98| Useful utilities (bars, launchers, screenshots, systemd, etc.) | **`references/useful-utilities.md`** |99| Crashes and bugs | **`references/crashes-and-bugs.md`** |100| Contributing to Hyprland | **`references/contributing.md`** |101102## Live Fetching103104When reference files are insufficient, fetch the latest docs from raw GitHub:105106```107https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/<section>/<page>.md108```109110Paths are lowercase. Section index pages are `_index.md`. Examples:111- `https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/configuring/core/config-options.md`112- `https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/configuring/core/advanced-configuration/using-hyprctl.md`113- `https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/hypr-ecosystem/user/hyprlock.md`114- `https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/nix/installing-hyprland-on-nixos.md`115116The `<!-- source: ... -->` header at the top of each reference file gives the matching wiki section.117118## Quick Reference (Hyprland 0.55+, Lua config)119120### Config file location121`~/.config/hypr/hyprland.lua` (or `$XDG_CONFIG_HOME/hypr/hyprland.lua`, override with `Hyprland --config`)122123### Options124```lua125hl.config({126 general = {127 border_size = 2,128 gaps_in = 5,129 },130})131```132Multiple `hl.config()` calls are allowed; each updates only what it receives.133134### Binds135```lua136hl.bind("SUPER + SHIFT + Q", hl.dsp.exec_cmd("firefox"))137hl.bind("SUPER + X", function()138 hl.dispatch(hl.dsp.window.float({ action = "toggle" }))139end)140```141142### Autostart143```lua144hl.on("hyprland.start", function()145 hl.exec_cmd("waybar & hyprpaper")146end)147```148149### Window rules150```lua151hl.window_rule({152 match = { class = "firefox" },153 opacity = 0.9,154 float = true,155})156```157158### Monitors159```lua160hl.monitor({161 output = "DP-1",162 mode = "1920x1080@144",163 position = "0x0",164 scale = 1,165})166```167168### Split config169```lua170require("conf/binds") -- ~/.config/hypr/conf/binds.lua171```172173### hyprctl runtime control174```sh175hyprctl reload176hyprctl eval 'hl.config({ general = { border_size = 3 } })'177hyprctl repl # interactive Lua REPL178hyprctl --batch "..."179```180181## Legacy (Hyprland 0.54 and earlier, hyprlang)182183Old-style `~/.config/hypr/hyprland.conf`:184185```ini186bind = MODS, key, dispatcher, params187general {188 border_size = 2189}190monitor = name, resolution@rate, position, scale191```192193Full legacy docs: https://wiki.hypr.land/0.54.0/
marceloeatworld