Hyprland Configuration Architecture

HyprFlux configures Hyprland 0.55 and newer 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.

This page explains how the pieces fit together. For the syntax, fields, and defaults of any single file, follow the link on its own reference page.

The configuration tree

~/.config/hypr/
├── hyprland.lua                 # compositor entrypoint
├── hyprflux-colors.lua          # generated Lua palette
├── monitors.lua                 # generated output rules
├── workspaces.lua               # generated workspace assignments
├── initial-boot.sh              # first-login fixup
├── 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
├── UserScripts/                 # user-owned helper scripts
├── hyprflux-colors/             # native .conf palette for Hyprlock and Hypridle
├── 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 tree is a map for orientation. Each file's own reference page documents its exact fields and defaults.

Which files you can edit

Every file in that tree falls into one of four groups.

The entrypoint. hyprland.lua does not hold your settings. It orchestrates the other modules by requiring them in a specific order. Edit it only to add, remove, or reorder a require(...) line. See the entrypoint reference for its exact contents.

User-owned modules. Most of UserConfigs/ is your customization surface: terminal and editor choice, input and layout behavior, decorations, animations, personal keybindings, window rules, and startup applications. Edit these freely.

Generated files. monitors.lua, workspaces.lua, and hyprflux-colors.lua are owned by tools, not by you. nwg-displays writes the monitor and workspace output, the installer hardware modules can regenerate monitor output, and utilities/sync-colors.sh generates the Lua palette. Hand-editing one of these is at best a temporary experiment, because the owning tool can overwrite it.

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

Even a user-owned file is not always entirely yours. The GPU marker block inside env-variables.lua, for example, is regenerated by the installer even though the rest of the file is editable. Read a file's own comments before you assume it is entirely yours.

Why load order matters

It is tempting to read the module list in hyprland.lua top to bottom as "later wins", the way some configuration systems work. HyprFlux's Lua modules do not 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 inconsistent:

• 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 return Lua tables. See the entrypoint reference for the full order.
• Why some keybindings collide. Because a later hl.bind does not remove an earlier one, the shipped source registers more than one action on SUPER+K, SUPER+O, and SUPER+SHIFT+W. Both actions run on every press. This is what "additive, not overriding" means in practice. See the full list in the Hyprland keybindings reference.

Coming from the old .conf layout

If you used 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. Do not 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.