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

> Discover how Omarchy loads Hyprland configuration files. Explore the layered structure and Lua bootstrap system that customizes your desktop environment.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-09

---

**Omarchy loads Hyprland configuration through a Lua-based bootstrap system at [`config/hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/config/hypr/hyprland.lua) that assembles a layered stack: core defaults from [`default/hypr/omarchy.lua`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/config/hypr/hyprland.lua). This file serves as the primary entry point that orchestrates the entire configuration load order.

The standard [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/hypr/monitors.lua)** – Display output definitions, scaling factors, and transformations
- **[`hypr/input.lua`](https://github.com/omacom/omarchy/blob/main/hypr/input.lua)** – Keyboard layouts, mouse sensitivity, and touchpad settings
- **[`hypr/bindings.lua`](https://github.com/omacom/omarchy/blob/main/hypr/bindings.lua)** – Personal keybinding overrides and shortcuts
- **[`hypr/looknfeel.lua`](https://github.com/omacom/omarchy/blob/main/hypr/looknfeel.lua)** – Visual tweaks including gaps, rounding, and animations
- **[`hypr/autostart.lua`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/envs.lua) for environment variables, [`looknfeel.lua`](https://github.com/omacom/omarchy/blob/main/looknfeel.lua) for baseline aesthetics, [`input.lua`](https://github.com/omacom/omarchy/blob/main/input.lua) for default input handling, [`windows.lua`](https://github.com/omacom/omarchy/blob/main/windows.lua) for window management rules, and [`qconsole.lua`](https://github.com/omacom/omarchy/blob/main/qconsole.lua) for console integration.

Finally, [`omarchy.lua`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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:

```lua
-- 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`](https://github.com/omacom/omarchy/blob/main/config/hypr/bindings.lua):

```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`](https://github.com/omacom/omarchy/blob/main/config/hypr/monitors.lua):

```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`](https://github.com/omacom/omarchy/blob/main/config/hypr/looknfeel.lua):

```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`](https://github.com/omacom/omarchy/blob/main/config/hypr/hyprland.lua)
- The **bootstrap process** in [`default/hypr/bootstrap.lua`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/default/hypr/helpers.lua) abstract Hyprland configuration syntax into programmatic Lua calls
- **Optional module loading** via [`default/hypr/require_optional.lua`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/monitors.lua) for display configuration, [`input.lua`](https://github.com/omacom/omarchy/blob/main/input.lua) for keyboard and mouse settings, [`bindings.lua`](https://github.com/omacom/omarchy/blob/main/bindings.lua) for key shortcuts, [`looknfeel.lua`](https://github.com/omacom/omarchy/blob/main/looknfeel.lua) for visual appearance, and [`autostart.lua`](https://github.com/omacom/omarchy/blob/main/autostart.lua) for startup programs. These are automatically loaded by [`config/hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/config/hypr/bindings.lua).