How Hyprland Configuration Files Under config/hypr/ Are Structured and Loaded

Omarchy loads Hyprland configuration through a Lua-based bootstrap system at config/hypr/hyprland.lua that assembles a layered stack: core defaults from default/hypr/omarchy.lua followed by user overrides for monitors, input, bindings, appearance, and autostart.

Omarchy is an opinionated Linux distribution that customizes the Hyprland compositor through a sophisticated Lua configuration system. Unlike standard Hyprland configuration files that use the native INI-like format, Omarchy leverages Lua modules under config/hypr/ to create a modular, reloadable configuration stack that separates system defaults from personal customizations.

The Bootstrap and Module Path Resolution

The configuration loading process begins with default/hypr/bootstrap.lua. This file performs critical environment setup before any Hyprland-specific configuration is evaluated.

The bootstrap sets the Lua package.path to include three key locations in order of priority:

• ~/.local/state – User state modules
• ~/.config – User configuration modules
• $OMARCHY_PATH – Omarchy system defaults

This path resolution ensures user files in config/hypr/ take precedence over system defaults.

The bootstrap also implements a cache-clearing mechanism through the reload_prefixes table. It iterates through package.loaded and removes any modules whose names start with default.hypr, hypr, or omarchy.current.theme. This allows the omarchy-reload command to pick up configuration changes immediately without requiring a full logout.

User Entry Point and the Configuration Stack

All user customization flows through config/hypr/hyprland.lua. This file serves as the primary entry point that orchestrates the entire configuration load order.

The standard hyprland.lua performs four distinct operations:

1. Loads the bootstrap (line 4) to initialize module paths
2. Optionally disables default bindings by setting omarchy_default_bindings or omarchy_preinstalled_bindings to false before the defaults load
3. Requires core Omarchy defaults via require("default.hypr.omarchy")
4. Loads user-specific overrides in a fixed sequence

The user override modules follow a strict naming convention under config/hypr/:

• hypr/monitors.lua – Display output definitions, scaling factors, and transformations
• hypr/input.lua – Keyboard layouts, mouse sensitivity, and touchpad settings
• hypr/bindings.lua – Personal keybinding overrides and shortcuts
• hypr/looknfeel.lua – Visual tweaks including gaps, rounding, and animations
• hypr/autostart.lua – Additional services and programs to launch on startup

This layered approach ensures personal settings override defaults without modifying system files.

Core Omarchy Defaults and Helpers

After the bootstrap completes, default/hypr/omarchy.lua establishes the baseline Hyprland configuration. This file acts as the central hub that imports helper utilities and conditionally loads default functionality.

The file first imports default/hypr/helpers.lua, which exposes critical functions used throughout the configuration:

• o.bind(key, name, command) – Creates Hyprland keybindings with metadata
• hl.monitor(opts) – Generates monitor configuration strings from Lua tables
• hl.config(table) – Translates nested Lua tables into Hyprland configuration syntax

The core defaults then load autostart.lua for system services and conditionally include bundled binding sets for media controls, clipboard management, tiling operations, and utility shortcuts—unless disabled by user variables.

Additional modules loaded include envs.lua for environment variables, looknfeel.lua for baseline aesthetics, input.lua for default input handling, windows.lua for window management rules, and qconsole.lua for console integration.

Finally, omarchy.lua attempts to load omarchy.current.theme.hyprland through the optional module loader, allowing themes to inject their own visual configurations.

Safe Optional Module Loading

To prevent configuration errors from missing files, Omarchy implements default/hypr/require_optional.lua. This utility provides a safe wrapper around Lua's require() that only loads a module if the file exists.

This mechanism enables:

• Theme packs that may or may not include Hyprland-specific overrides
• User-installed extra bindings that aren't part of the base system
• Graceful degradation when optional configuration files are absent

The function returns nil silently if the module path cannot be resolved, ensuring the configuration stack continues loading without interruption.

Configuration Reload Behavior

The reload mechanism relies entirely on the bootstrap's cache management. When executing omarchy-reload, the system triggers the bootstrap sequence again.

Because the bootstrap clears all previously loaded modules matching the defined prefixes, Lua treats subsequent require() calls as first-time loads. This forces re-evaluation of:

• All default configurations in default/hypr/
• All user overrides in config/hypr/
• Any active theme modifications

The result is a complete configuration refresh without restarting Hyprland or losing the current session state.

Practical Configuration Examples

A minimal user entry point at ~/.config/hypr/hyprland.lua follows this structure:

-- Load Omarchy bootstrap (sets module path & clears caches)
dofile((os.getenv("OMARCHY_PATH") or "/usr/share/omarchy") .. "/default/hypr/bootstrap.lua")

-- Load Omarchy core defaults
require("default.hypr.omarchy")

-- Personal overrides -------------------------------------------------
require("hypr.monitors")   -- monitor definitions
require("hypr.input")      -- keyboard / mouse tweaks
require("hypr.bindings")   -- personal keybindings
require("hypr.looknfeel")  -- visual tweaks
require("hypr.autostart")  -- extra services

To add a custom keybinding in config/hypr/bindings.lua:

-- Bind SUPER+SHIFT+T to open a terminal
o.bind("SUPER + SHIFT + T", "Terminal", "alacritty")

For custom monitor scaling in config/hypr/monitors.lua:

local scale = "1.25"                -- 125 % scaling
hl.monitor({ output = "", mode = "preferred", position = "auto", scale = scale })

To override the default layout engine in config/hypr/looknfeel.lua:

hl.config({
  general = { layout = "scrolling" },
  scrolling = { column_width = 0.97 },
})

Summary

• Omarchy uses Lua modules rather than native Hyprland configuration syntax, with the entry point at config/hypr/hyprland.lua
• The bootstrap process in default/hypr/bootstrap.lua configures module paths and clears caches to enable live reloading
• Configuration follows a strict load order: bootstrap → core defaults (default/hypr/omarchy.lua) → user overrides (monitors, input, bindings, looknfeel, autostart) → optional themes
• The o.bind and hl.monitor helper functions in default/hypr/helpers.lua abstract Hyprland configuration syntax into programmatic Lua calls
• Optional module loading via default/hypr/require_optional.lua allows themes and extensions to exist without breaking the base configuration
• The omarchy-reload command triggers the bootstrap cache-clearing mechanism, enabling configuration changes without session restart

Frequently Asked Questions

What file format does Omarchy use for Hyprland configuration?

Omarchy uses Lua source files rather than Hyprland's native INI-like configuration format. The system translates Lua tables and function calls into Hyprland configuration directives at runtime through helper functions defined in default/hypr/helpers.lua.

Where do I put my personal Hyprland settings in Omarchy?

Place personal settings in the ~/.config/hypr/ directory within five specific files: monitors.lua for display configuration, input.lua for keyboard and mouse settings, bindings.lua for key shortcuts, looknfeel.lua for visual appearance, and autostart.lua for startup programs. These are automatically loaded by config/hypr/hyprland.lua after the system defaults.

How do I reload Hyprland configuration changes in Omarchy?

Execute the omarchy-reload command from a terminal or keybinding. This triggers the bootstrap sequence in default/hypr/bootstrap.lua to clear cached modules and re-evaluate the entire configuration stack, applying changes immediately without closing windows or ending the session.

Can I disable Omarchy's default keybindings?

Yes. Set omarchy_default_bindings = false or omarchy_preinstalled_bindings = false in your config/hypr/hyprland.lua before the line that calls require("default.hypr.omarchy"). This prevents the core defaults from loading the bundled media, clipboard, tiling, and utility binding sets, allowing you to define all shortcuts from scratch in your personal config/hypr/bindings.lua.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}