Hyprland in Omarchy: windows, configuration and diagnosis

Hyprland is the Wayland compositor managing your desktop’s application surfaces, window layout, workspaces, displays and input focus. It is central to Omarchy, but it is not the whole operating system or every desktop service. The upstream introduction explicitly distinguishes the compositor from a complete desktop environment. Omarchy supplies the surrounding choices and integration.

Use the desktop layer for the category-wide component list. This entity guide connects the responsibilities to concrete inspection and configuration decisions.

How an application becomes a usable desktop window

login entry → UWSM-managed session context
  → Hyprland
      ← application surfaces (native Wayland, or X11 via XWayland)
      → monitor output, placement and input focus
      ↔ Quickshell's bar/menu surfaces and desktop state
      ↔ desktop portal integration for app requests such as screen sharing

The diagram shows responsibility, not an identical process tree for every installation. UWSM manages the session lifecycle/environment; Hyprland remains responsible for presenting windows. Quickshell supplies the UI controls. A portal mediates capabilities for applications rather than arranging your tiling layout.

Component	Does	Does not replace
SDDM	Login entry and launching the selected session	The running compositor
UWSM	Session/environment and user-service coordination	Window layout rules
Hyprland	Focus, placement, workspaces, outputs and input	NetworkManager, media server or app package manager
Quickshell	Desktop bar, menus, panels and shell services	The compositor
XWayland	Compatibility for X11 applications in a Wayland session	The native Wayland application path
Desktop portal	App-facing desktop capabilities and mediation	All screen capture or app rendering itself

A missing network indicator can be a UI fault while networking still works. A visible menu with no connection can be a network-service fault. Likewise, working windows with a missing bar point to a different layer from a session that immediately returns to login.

Identify your configuration generation

Omarchy and upstream documentation evolve. Run hyprctl version inside the active session and record the installed Omarchy release. Check whether your personal entry is ~/.config/hypr/hyprland.lua or an older .conf layout. The upstream core configuration guide has a version selector; match it to the installation rather than copying the latest Git documentation blindly.

This page’s Omarchy file map is the pinned Lua snapshot. Its entry point loads bootstrap, defaults, personal modules and toggles:

hyprland.lua → bootstrap
  → default.hypr.omarchy (includes defaults and current theme)
  → personal monitors / input / bindings / looknfeel / autostart
  → dynamic toggles
  → additional personal entry-file code

Do not paste this sequence again into the file. It explains the existing setup. Personal files follow defaults, but rules and bindings are not universally “last line wins”; adding a duplicate binding can add behavior instead of removing the original.

Choose a file by the responsibility

Task	Pinned personal file	Detailed guide
Monitor arrangement/scale	monitors.lua	Displays
Layout, mouse and keyboard input	input.lua	Configuration model
Add/replace global key actions	bindings.lua	Keybindings
Gaps, borders and animations	looknfeel.lua	Window appearance
Start extra apps	autostart.lua	Autostart
App placement/matching	Appropriate personal rule configuration	Window rules
Bar widgets and menus	Omarchy shell configuration, not a Hyprland layout file	Bar

Keep packaged defaults under $OMARCHY_PATH/default/hypr/ as reference. Make durable changes in personal files and preserve the original. Changing generated current-theme output is not a persistent window configuration strategy.

Read runtime state before writing a rule

Inside a working Hyprland session, use these queries individually:

hyprctl version
hyprctl monitors
hyprctl clients
hyprctl activewindow
hyprctl workspaces

The upstream hyprctl guide documents the control interface. monitors identifies output names, modes and scale; clients describes windows; activewindow narrows the currently focused client; workspaces shows actual workspace state. A client title can change, while its app class may be a better matching input. Do not invent an app identifier from its launcher label.

Example: a browser keeps opening on the wrong workspace. Open the actual browser, focus it, inspect its reported identity and workspace, then compare the rule you intended to match. If the identity differs, the rule’s target is wrong. If the identity matches but later behavior moves the window, investigate other rules or startup actions. The window-rule guide supplies a version-scoped edit and undo; the entity page’s inspection prevents guessing the target.

Queries are not commands to create a second compositor. “Cannot connect” from an ordinary console or SSH environment can mean that it lacks the running session’s IPC context; it does not alone prove the compositor executable is missing. hyprctl clients may include document titles or private paths, so trim these before posting output.

Route failures by stage and surface

Observation	Start here
No login screen	Boot/login service; boot layer and SDDM
Login immediately returns	Session startup, config error or compositor failure
Windows work, bar is absent	Quickshell health
One output uses the wrong scale	Monitor state, connection and personal monitor configuration
One key launches two actions	Duplicate bindings and interception
One application renders poorly	Native Wayland/XWayland path, that app’s scale/rendering settings
Screen-sharing selection fails	Portal/session integration; capture guide

Record the earliest failure and last changed file. Where supported, hyprctl configerrors can identify configuration errors; do not treat an empty result as a GPU diagnosis. Restoring the saved personal file and reloading is a narrower first response than resetting all desktop settings.

Learn and change without losing your session

Start with inspection, then one small configuration exercise, then a task-specific guide. A config reload reevaluates configuration; logging out ends the session and may close apps. Do not restart the compositor casually to fix a menu. Save work before session-changing actions, and retain a way to restore the edited file if the desktop no longer opens.

For a useful upstream report, include both versions, exact error, affected output/app and minimal relevant configuration. Omarchy defaults are part of the setup; a generic Hyprland tutorial does not establish how those defaults are loaded. That integration context is the reason to use this guide alongside the upstream Wiki.