# What Window Manager Does Omarchy Use? Understanding the Hyprland Foundation

> Discover the Hyprland window manager powering Omarchy. Learn how Omarchy leverages Hyprland for a streamlined and customizable desktop experience.

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

---

**Omarchy uses the Wayland tiling window manager Hyprland as its core compositor and window manager, launching it automatically via `uwsm` and configuring it through Lua scripts generated from Omarchy's theme system.**

If you're exploring the Omarchy Linux distribution, you're likely wondering what window manager powers its desktop experience. According to the Omarchy source code, Hyprland serves as the foundational compositor handling everything from workspace management to monitor layouts, while Omarchy provides a sophisticated layer of tooling and theming on top.

## Why Omarchy Chose Hyprland

Hyprland is a modern, feature-rich tiling window manager for Wayland. The Omarchy welcome manual explicitly describes the distribution as "the tiling window manager **Hyprland**" in its opening lines, establishing Hyprland as the centerpiece of the desktop architecture.

This choice gives Omarchy several advantages:

- **Native Wayland support** without X11 compatibility layers
- **Advanced tiling features** including dynamic layouts, window rules, and per-monitor workspaces
- **Extensive customization** through its Lua configuration interface
- **Active development** with regular feature additions and performance improvements

## How Omarchy Configures Hyprland

Unlike standard Hyprland installations where users edit raw configuration files, Omarchy generates Hyprland configurations dynamically from its theme system.

### Configuration Generation Pipeline

Configuration flows through this path in the Omarchy repository:

1. **Theme template**: `default/themed/hyprland.lua.tpl` contains the base structure
2. **Theme processing**: Omarchy's theming engine renders this template into a concrete [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua)
3. **User loading**: The generated file is `require`-ed from `~/.config/hypr/hyprland.lua`

The [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md) file documents this pipeline at lines 352‑355, showing how themes transform into runnable Hyprland configuration.

### Default Configuration Location

The base Hyprland configuration ships at [`config/hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/config/hypr/hyprland.lua) in the Omarchy repository. This file provides sensible defaults that themes can extend or override.

## Hyprland Integration in the Omarchy Session

Omarchy doesn't just install Hyprland—it deeply integrates it into the session lifecycle.

### Session Startup via UWSM

The Omarchy session uses `uwsm` (Universal Wayland Session Manager) to launch Hyprland. As documented in [`shell/README.md`](https://github.com/omacom/omarchy/blob/main/shell/README.md) at lines 4‑5, Hyprland starts immediately and then launches the Quickshell-based shell as its UI layer. This creates a clean separation: Hyprland manages windows and compositing, while Quickshell draws panels, notifications, and other chrome.

### Runtime Management

The [`default/agents/skills/omarchy/hyprland.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/hyprland.md) file serves as the canonical reference for Hyprland settings within Omarchy. It documents:

- Auto-reload behavior when configurations change
- Validation workflows using `hyprctl configerrors`
- Window rule syntax for application-specific behavior
- Monitor handling and workspace assignment

## Practical Hyprland Operations in Omarchy

Below are concrete examples of working with Hyprland in an Omarchy environment.

### Querying Hyprland State

Use `hyprctl` to inspect the running compositor:

```bash

# List all connected monitors and their properties

hyprctl monitors

# Show workspace distribution across outputs

hyprctl workspaces

# Reload configuration and check for errors

hyprctl reload && hyprctl configerrors

```

### Creating a User Configuration File

A minimal `~/.config/hypr/hyprland.lua` that respects Omarchy's theming:

```lua
-- Load Omarchy-provided base configuration
dofile(os.getenv("OMARCHY_PATH") .. "/config/hypr/hyprland.lua")

-- Load a custom theme (e.g., the "kanagawa" theme)
local theme = require("themes.kanagawa")
theme.apply()

-- User overrides follow theme application
-- Example: increase border width for visibility
decoration.border_size = 2

```

### Defining Window Rules

Hyprland's `windowrulev2` syntax controls where applications appear:

```lua
-- Direct all terminal windows to workspace 2
windowrulev2 = {
    { "workspace 2", "class:.+Term" },
}

-- Make dialog windows float instead of tiling
windowrulev2 = {
    { "float", "title:^(Open|Save) File" },
}

```

### Using Omarchy Helper Commands

Omarchy wraps common Hyprland toggles in convenience commands:

```bash

# Toggle window borders on/off

omarchy-toggle-hyprland-borders

# Switch between predefined gap sizes

omarchy-cycle-hyprland-gaps

```

## Key Source Files for Hyprland in Omarchy

| File Path | Purpose |
|-----------|---------|
| [`manual/01-welcome-to-omarchy.md`](https://github.com/omacom/omarchy/blob/main/manual/01-welcome-to-omarchy.md) | Introductory description confirming Hyprland as the WM |
| [`default/agents/skills/omarchy/hyprland.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/hyprland.md) | Detailed configuration guide and reload workflows |
| `default/themed/hyprland.lua.tpl` | Theme-to-config transformation template |
| [`config/hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/config/hypr/hyprland.lua) | Default runtime configuration |
| [`shell/README.md`](https://github.com/omacom/omarchy/blob/main/shell/README.md) | Relationship between Hyprland and Quickshell |

## Summary

- **Omarchy's window manager is Hyprland**, a modern Wayland tiling compositor
- Configuration is **Lua-based** and **theme-driven**, generated from templates in `default/themed/`
- The session launches Hyprland via **`uwsm`**, which then starts the Quickshell UI layer
- Users customize behavior through **`~/.config/hypr/hyprland.lua`** or theme selection
- Runtime control uses standard **`hyprctl`** commands plus Omarchy helper scripts

## Frequently Asked Questions

### Is Hyprland required for Omarchy, or can I swap it for another window manager?

Hyprland is tightly integrated into Omarchy's architecture. The theming system, session startup, and shell components all assume Hyprland's presence. While technically possible to modify the source, Omarchy does not support alternative window managers and would require substantial changes to [`shell/README.md`](https://github.com/omacom/omarchy/blob/main/shell/README.md) and [`default/agents/skills/omarchy/hyprland.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/hyprland.md) infrastructure.

### How do I reload Hyprland configuration without logging out?

Run `hyprctl reload` from any terminal, then verify with `hyprctl configerrors`. Omarchy's Hyprland skill documentation at [`default/agents/skills/omarchy/hyprland.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/hyprland.md) recommends this two-step workflow to catch syntax errors immediately.

### Where does Omarchy store the generated Hyprland configuration?

Omarchy renders themes into a [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua) file that your user config loads via `require`. The exact path depends on your active theme, but the entry point is always `~/.config/hypr/hyprland.lua`, which in turn loads [`OMARCHY_PATH/config/hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/OMARCHY_PATH/config/hypr/hyprland.lua) and any theme-specific additions.

### Can I use standard Hyprland configuration syntax in Omarchy?

Yes, with caveats. Omarchy's Lua-based configuration ultimately generates standard Hyprland directives. You can embed raw Hyprland config syntax within Lua strings, or modify [`config/hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/config/hypr/hyprland.lua) directly. However, theme-generated settings may override manual changes depending on load order.