Read this layer as login entry → session management → window presentation. These responsibilities connect, but session management and compositing continue working throughout the desktop session.
Presents application surfaces and assigns focus inside the session
Example: logging in and opening a terminal. SDDM starts the selected session. For a UWSM-managed session, UWSM coordinates startup and environment, while Hyprland manages the desktop. The terminal draws its contents; Hyprland controls its placement and focus. The bar and menus supplied by Quickshell belong to a separate interface layer.
A missing login screen, an immediate return after login, and incorrect window placement therefore suggest different starting points: SDDM, session startup, and Hyprland configuration. This describes responsibilities, not an identical process tree for every installation.
Each catalogued component is explained below: purpose, architecture, configuration, troubleshooting, limitations and further reading. Use the component links to jump to its explanation.
Controls window placement, workspaces, focus, monitor layout and input in a Wayland session. It is the right layer for changing how windows behave, rather than what the desktop bar displays.
How it works and connects
Applications submit surfaces to the compositor, which combines them for display and routes input. UWSM manages session lifetime; portals connect applications to desktop-mediated features.
Configuration and customization
This Omarchy snapshot documents ~/.config/hypr/hyprland.lua and separate Lua overrides for monitors, input and bindings. Match the installed Hyprland version before borrowing upstream examples.
Troubleshooting approach
Inspect hyprctl version and monitor information, then isolate one override at a time. Distinguish a single application failing to render from the entire compositor failing to start.
Limits and change considerations
Restarting or replacing the compositor affects the whole graphical session. Keep a copy of working overrides; do not overwrite managed defaults to customize one setting.
Local inspection and version checks
Read local package metadata to confirm installation and version. These inspection commands do not install, restart or change configuration; run them in your own Omarchy environment.
pacman -Qi hyprland
hyprctl version
Queries can fail when a package is absent, a service is stopped, or the command needs a graphical session or project directory. Interpret the result in context. Review machine-specific details before sharing output.
Omarchy integration follows the 2026-10-12 quattro snapshot. Match upstream configuration guidance to your installed version. These are documentation-based explanations and diagnostic suggestions, not hardware-tested results.
Manages a Wayland session through systemd user services.
Package
uwsm
Membership
Core manifest
Purpose and everyday use
Coordinates the Wayland session and application lifecycle with systemd user services. Most users encounter it indirectly when logging in, launching applications or ending a session.
How it works and connects
Session environment and service ordering matter: an application launched in the wrong context may lack the variables available inside the desktop. Hyprland still performs compositing.
Configuration and customization
Follow UWSM’s documented environment and session configuration. Prefer Omarchy’s supported autostart mechanism for ordinary applications rather than manually starting another compositor.
Troubleshooting approach
Check failed user services and the user journal when startup or logout hangs. Compare launching inside the desktop with launching from an unrelated terminal session.
Limits and change considerations
It is not a window manager or login screen. Running duplicate session managers can produce confusing service and environment behavior.
Local inspection and version checks
Read local package metadata to confirm installation and version. These inspection commands do not install, restart or change configuration; run them in your own Omarchy environment.
pacman -Qi uwsm
systemctl --user --failed
Queries can fail when a package is absent, a service is stopped, or the command needs a graphical session or project directory. Interpret the result in context. Review machine-specific details before sharing output.
Omarchy integration follows the 2026-10-12 quattro snapshot. Match upstream configuration guidance to your installed version. These are documentation-based explanations and diagnostic suggestions, not hardware-tested results.
Display manager that starts the graphical login session.
Package
sddm
Membership
Core manifest
Purpose and everyday use
Provides the display-manager stage that starts a graphical user session. Login appearance and session selection belong here; a lock screen inside an existing session is separate.
How it works and connects
A system service manages the login process and hands off to a selected session. Omarchy’s enable-services script enables sddm.service; UWSM and Hyprland operate further along the chain.
Configuration and customization
SDDM has its own configuration and theme system. Review the installed configuration before altering automatic login, session choice or themes; these are not Hyprland window rules.
Troubleshooting approach
If the login screen never appears, inspect the system service. If login returns immediately to the greeter, inspect the selected session and user logs as well.
Limits and change considerations
Restarting the display manager can terminate graphical sessions. Theme failures should not prompt unrelated authentication changes.
Local inspection and version checks
Read local package metadata to confirm installation and version. These inspection commands do not install, restart or change configuration; run them in your own Omarchy environment.
pacman -Qi sddm
systemctl status sddm --no-pager
Queries can fail when a package is absent, a service is stopped, or the command needs a graphical session or project directory. Interpret the result in context. Review machine-specific details before sharing output.
Omarchy integration follows the 2026-10-12 quattro snapshot. Match upstream configuration guidance to your installed version. These are documentation-based explanations and diagnostic suggestions, not hardware-tested results.