What Window Manager Does Omarchy Use? Understanding the Hyprland Foundation

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
3. User loading: The generated file is require-ed from ~/.config/hypr/hyprland.lua

The 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 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 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 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:

# 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:

-- 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:

-- 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:

# 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	Introductory description confirming Hyprland as the WM
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	Default runtime configuration
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 and 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 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 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 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 directly. However, theme-generated settings may override manual changes depending on load order.

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