Repository navigation
Hyprland Settings
Everything Hyprland itself does — your keyboard, your mouse, the tiling engine, your shortcuts, your window rules — can now be changed from Settings → Hyprland, without opening a text editor.
It's one page with six tabs, and it writes real Lua into your own ~/.config/hypr/custom/ files. Nothing is hidden in a database somewhere: whatever you set here you can read back, copy to another machine, or delete by hand.
Requires Hyprland 0.56.1+ (the native Lua config system).
- Press Super + I to open Settings, then pick Hyprland in the sidebar.
- Change something — the keyboard layout, the mouse speed, the tiling engine.
- That's it. The change is written and Hyprland reloads on its own.
Want to see exactly what the page has done to your config? The strip at the top of every tab has Review — it shows you the Lua, as it sits on disk, plus anything not written yet. Next to it, Remove all takes every managed setting back out again and leaves your own Lua alone.
The page never touches ~/.config/hypr/hyprland/ — those files are replaced on every update, so anything written there would vanish. Instead it appends a fenced block at the end of the matching file in ~/.config/hypr/custom/:
-- >>> quickshell:managed:begin v1 - written by Settings -> Hyprland.
hl.config({ input = { kb_layout = "fr,us" } })
-- <<< quickshell:managed:endAnything you wrote above those markers is left completely alone — the page reads it, tells you it's there, and never rewrites it. custom/ is loaded after the defaults, so the block wins over the stock config without modifying it.
Each file is backed up before a write, into ~/.local/state/quickshell/hyprland-backups/.
Settings land in the file they belong to: general options in custom/general.lua, rules in custom/rules.lua, shortcuts in custom/keybinds.lua, environment variables in custom/env.lua, app names in custom/variables.lua.
Keyboard layout and variant (with a searchable XKB picker), key repeat rate and delay, mouse sensitivity and acceleration, natural scroll, touchpad behaviour — tap to click, drag lock, scroll factor, disable while typing — and cursor size, hide-on-idle and hide-while-typing.
At the bottom, Per device: every keyboard, mouse and touchpad Hyprland can see, each able to override the global settings just for itself. Handy when your laptop's touchpad and your desk mouse want opposite scroll directions.
Which engine arranges your windows — dwindle, master, scrolling or monocle — with only that engine's own options shown underneath, plus a small diagram of where the next window would land.
Also here: focus behaviour, workspace back-and-forth, and Hyprland's own workspace swipe gestures.
Every keyboard shortcut on the system, grouped the way the Cheat Sheet groups them, each showing which file it came from.
Any shortcut can be changed — including the stock ones. Because binding a key that's already bound registers both, the page always writes a release followed by the new bind, so replacing a default actually replaces it. Press a key combination to capture it, or type it by hand if your keyboard makes that awkward.
The editor won't let you save a set of shortcuts with no way to open a terminal and no way to reach the session menu — that's the one mistake you'd need a TTY to undo.
Underneath is the other half of a shortcut: the app it opens. Those are lists of candidates tried in order (so the config still works on a machine that has none of your usual programs), and each one has its own editor showing which candidate is actually installed and therefore which one wins.
Shortcuts are read from your config files, not from
hyprctl. On a Lua confighyprctl bindsreportsdispatcher: "__lua"for everything, so it knows which keys are taken and nothing at all about what they do — the page uses it only to spot conflicts.
Per-app cards for the things people actually want — always float this, always open on that workspace, make this one opaque. Rather than making you guess an app's window class, there's a picker listing your installed apps and your currently open windows; picking an open one uses the class it really has. Every rule shows a live preview of which open windows it currently matches.
Below that, raw window rules, layer rules and workspace rules for anything the cards don't cover.
Cursor theme and size, applied live, plus environment variables — grouped presets for the common ones (Firefox on Wayland, Qt scaling, NVIDIA) and a free-form list for the rest.
Environment variables only take effect for programs started afterwards, so the page says so plainly rather than pretending the change was instant.
Every option Hyprland has — all 353 of them — searchable, grouped by section, with the right kind of editor for each: a switch for booleans, a number field for integers, a colour picker for colours, a gradient editor for gradients.
The list isn't written into the shell. It's read from the type declarations Hyprland installs at /usr/share/hypr/stubs/hl.meta.lua, so a new Hyprland release's options show up without the shell needing an update. If your distribution doesn't ship that file, a bundled copy is used and the page tells you it fell back.
Options that have a proper control on another tab say so and link there instead of showing you a raw value. Options the shell itself owns — gaps, borders, rounding, blur — are shown read-only, with a link to the page that really controls them, because a control that visibly reverts is worse than no control.
debug.* is hidden behind a switch in Advanced, and off again after a restart. One of those options crashes the compositor on purpose.
Modes & Routines can outrank this page. hyprland/shellOverrides/main.lua loads last, so an active Mode (Game Mode, for instance) shadows anything set here. The page detects that and labels it rather than letting you wonder why nothing happened.
Hand-written lines are respected. If you already set something above the managed block, the page shows the value, tells you where it came from, and offers to remove the now-dead line rather than silently writing a second one.
Reloads are batched. One config write produces roughly six configreloaded events, so edits are debounced and written once per batch.
- The Cheat Sheet (Super + /) has an edit button in its bottom toolbar that jumps straight to the Shortcuts tab.
- A routine's shortcut trigger has a Bind a key button that opens the shortcut editor with the routine already filled in — or Change the key, if it already has one.
- The Windows settings page links here for the tiling engine.
- Keybinds — the default shortcuts and how the Lua bind system works
- Configuration Reference — where every config file lives
- Modes & Routines — the layer that can shadow these settings
- Customization — theming, and the shell-owned appearance settings