Customise
Recipes for the most common changes, each shown as a diff, in places updates never overwrite.
Where changes go
Hyprland reads its config in this order; later files win:
Rule of thumb
Use Settings when it has the option. Put everything else in ~/.config/hypr/user.lua. Don't edit
hyprland.lua itself: the next update would replace it.
Hyprland reloads on save. After any edit, check for mistakes:
hyprctl configerrors # empty = all goodRecipes
By default every screen uses its preferred mode. hyprctl monitors lists the names.
-- Your own Hyprland settings. Loaded last; updates never touch this file.
+hl.monitor({ output = "eDP-1", mode = "1920x1080@144", position = "0x0", scale = 1 })
+hl.monitor({ output = "HDMI-A-1", mode = "2560x1440@165", position = "auto-right", scale = 1 })Settings → Keyboard does this without a file. As code:
+hl.bind("SUPER + B", hl.dsp.exec_cmd("firefox"), { description = "Browser" })
+hl.bind("SUPER + SHIFT + P", hl.dsp.exec_cmd("qs ipc call shell power"), { description = "Power menu" })The description appears in the shortcut sheet (Win+/).
Settings → Windows & Effects, or:
+hl.config({
+ general = { gaps_in = 8, gaps_out = 16 },
+ decoration = { rounding = 24 },
+})Right-click an app in the dock → Pin / Unpin, or Settings → Desktop & Dock. It is stored as desktop-file names:
{
"pinned": [
"firefox",
"com.mitchellh.ghostty",
- "yazi",
+ "code",
"mvpdots-settings"
]
}Dim after 15 minutes, lock at 20, screen off 30 seconds later, sleep at 30 (battery only). Times are in seconds:
# dim (any power source)
listener {
- timeout = 900
+ timeout = 300
on-timeout = ~/.local/bin/idle-step dim
on-resume = ~/.local/bin/idle-step undim
}Then systemctl --user restart hypridle.
-dir=~/Pictures/Screenshots; mkdir -p "$dir"
+dir=~/Nextcloud/Screenshots; mkdir -p "$dir"~/.local/bin/snap is replaced by updates; re-apply after git pull && ./install.sh, or keep a copy.
hypr-plugins offGlass falls back to normal blur, title bars disappear, everything else is unchanged.
What Settings writes
Settings → Windows & Effects stores only the values you change in look.json, then generates look.lua.
Delete both to go back to hyprland.lua's values.
-- Generated by Settings → Windows & Effects (HyprLook.qml). Do not edit by hand:
-- change it in Settings, or delete this file to go back to hyprland.lua's values.
hl.config({
decoration = {
blur = { brightness = 1.15, contrast = 2, noise = 0.01, xray = false },
shadow = { range = 30, render_power = 4 },
rounding = 20,
},
general = { border_size = 0 },
})Editing the shell
The shell lives in ~/.config/quickshell/ (shell.qml is the entry point, one .qml file per piece). A syntax
error takes the whole bar down, so check before saving:
/usr/lib/qt6/bin/qmllint ~/.config/quickshell/Island.qml
journalctl --user -u quickshell -n 30 # look for "Configuration Loaded"
systemctl --user restart quickshell # if it didn't reload by itself