Lua configuration and your own changes
Which file does what, and how defaults, state and monitor geometry work together.
On this page
Entry point and structure
The shared Hyprland entry point leads to the Lua files in ~/.config/hypr/lua/. The previous configuration was split into separate areas of responsibility.
| File | Purpose |
|---|---|
init.lua | Loads plugins, options, rules, bindings and autostart. |
reference.lua | Shared portable base. |
state.lua | Current user state from the settings. |
host.lua | Optional personal overrides. |
geometry.lua | Derived screen and window geometry. |
bindings.lua | Keyboard and mouse bindings. |
Mind the precedence
User state is applied on top of the shared base. Personal options are only used where the user state does not already set them. For window rules, the base is followed by personal rules, user state and finally the computed geometry. An entry in host.lua therefore does not simply override every other source.
Keep your own changes traceable
For supported options, use the interface first. Back up the affected files before editing them by hand. Managed code that you changed locally is kept as a conflict during a package sync; you then have to merge new project changes yourself.
The shortcut table describes the bundled bindings. Your own changes in bindings.lua may differ from it.
As of 9 November 2026 · This help describes version 0.1.0-27. Individual features and labels may change.
← More help topicsReport a problem →