Hyprland Configuration Architecture

HyprFlux configures Hyprland 0.55+ through ~/.config/hypr/hyprland.lua. Lua is the only supported compositor format in the current release. Supporting tools such as Hyprlock and Hypridle still use their own .conf formats.

Source baseline: HyprFlux v1.5.0 at f421b6b.

This page explains how the pieces fit together conceptually. For the exact syntax, fields, and defaults of any one file, follow the links below to its own reference page.

The Shape of the Tree

Before the ownership rules below make sense, it helps to see the whole tree at once:

~/.config/hypr/
├── hyprland.lua                 # compositor entrypoint
├── hyprflux-colors.lua          # generated Lua palette
├── monitors.lua                 # generated output rules
├── workspaces.lua               # generated workspace assignments
├── configs/
│   └── keybinds.lua             # HyprFlux base bindings
├── UserConfigs/
│   ├── user-defaults.lua
│   ├── env-variables.lua
│   ├── user-settings.lua
│   ├── user-decorations.lua
│   ├── user-animations.lua
│   ├── user-keybinds.lua
│   ├── laptops.lua
│   ├── window-rules.lua
│   ├── workspace-rules.lua
│   ├── startup-apps.lua
│   └── LaptopDisplay.lua
├── animations/                  # selectable Lua presets
├── Monitor_Profiles/            # HyprFlux profile assets
├── scripts/                     # maintained desktop helpers
├── hyprlock.conf                # Hyprlock native configuration
├── hyprlock-1080p.conf          # optional low-resolution variant
├── hypridle.conf                # Hypridle native configuration
└── application-style.conf       # Hyprland Qt/QML application style

This is a map for orientation, not a lookup table - each file's own reference page documents its exact fields and defaults.

Four Kinds of Files, Four Editing Rules

Every file in that tree falls into one of four categories, and knowing which category a file belongs to tells you whether you should ever hand-edit it.

The entrypoint - hyprland.lua itself. It doesn't hold your settings; it orchestrates everything else by requiring modules in a specific order. You edit it only to add, remove, or reorder a require(...) line, not to change a setting directly. See the entrypoint reference for its exact contents.

User-owned modules - most of what's under UserConfigs/. These are your customization surface: terminal and editor choice, input and layout behavior, decorations, animations, personal keybindings, window rules, and startup applications. Edit these freely; each has its own reference page.

Generated files - monitors.lua, workspaces.lua, and hyprflux-colors.lua. A tool owns each of these, not you directly: nwg-displays writes monitor and workspace Lua output, installer hardware modules can regenerate monitor output and profiles, and utilities/sync-colors.sh generates the Lua palette from the central color source. Hand-editing one of these is a temporary experiment at best - the owning tool can overwrite it the next time it runs.

Distribution defaults - configs/keybinds.lua. This is the HyprFlux base binding layer, shipped and maintained by the project. Add your own bindings in UserConfigs/user-keybinds.lua instead of editing this file directly, so your changes survive an update.

Even "user-owned" isn't always absolute: the GPU marker block inside env-variables.lua, for example, is regenerated by the installer even though the rest of that file is yours to edit. Read a file's own comments before assuming it's entirely yours.

Why Load Order Is a Dependency Chain, Not a Priority List

It's tempting to read hyprland.lua's module list top-to-bottom as "later wins," the way some configuration systems work. HyprFlux's Lua modules don't work that way: requiring a module runs it once, in order, and nothing it registers is automatically replaced by anything that loads after it.

That single rule explains two things that otherwise look like inconsistencies:

• Why the environment module loads first. env-variables.lua must run before any other module that calls an hl.* function, because those calls can depend on environment state already being set. Defaults and the color palette can load before it only because they just return Lua tables - they don't call anything yet. See the entrypoint reference for the complete ordered list.
• Why some keybindings collide. Because a later hl.bind doesn't remove an earlier one, HyprFlux's own source currently registers more than one action on SUPER+K, SUPER+O, and SUPER+SHIFT+W - both actions run on every press. This isn't a menu or a fallback; it's what "additive, not overriding" means in practice. See the full list in the Hyprland keybindings reference.

Coming from the Old .conf Layout

If you're used to an older HyprFlux install, or a tutorial written before the Lua migration, the filenames changed along with the format:

Previous name	Current owner
hyprland.conf	hyprland.lua
01-UserDefaults.conf	UserConfigs/user-defaults.lua
ENVariables.conf	UserConfigs/env-variables.lua
UserSettings.conf	UserConfigs/user-settings.lua
UserDecorations.conf	UserConfigs/user-decorations.lua
UserAnimations.conf	UserConfigs/user-animations.lua
Keybinds.conf	configs/keybinds.lua
UserKeybinds.conf	UserConfigs/user-keybinds.lua
Laptops.conf	UserConfigs/laptops.lua
WindowRules.conf	UserConfigs/window-rules.lua
WorkSpaceRules	UserConfigs/workspace-rules.lua
LaptopDisplay.conf	UserConfigs/LaptopDisplay.lua
Startup_Apps.conf	UserConfigs/startup-apps.lua
monitors.conf compositor input	generated monitors.lua
workspaces.conf compositor input	generated workspaces.lua

Treat this table as a translation aid, not as valid current syntax - don't write new configuration in the removed format.

For Contributors

In the source repository, .config/ is canonical and base-dots/config/ is a byte-identical parity mirror enforced by HyprFlux CI. A configuration change proposed upstream needs both trees to agree.