uwsm
systemd session manager for standalone Wayland compositors
TLDR
SYNOPSIS
uwsm [-h] subcommand [options...]
DESCRIPTION
uwsm (Universal Wayland Session Manager) wraps a standalone Wayland compositor in systemd user units. It handles environment export/cleanup, XDG autostart, binding the graphical session to the login session, and clean shutdown. Hyprland, Sway, Niri, labwc, wayfire, and mango have plugins.uwsm start -- compositor launches an executable, a wayland-sessions desktop-entry ID, select, or default. uwsm app starts programs as scopes (default) or services in app-graphical.slice so they are not children of the compositor unit. Omarchy includes uwsm in its base packages.A typical TTY profile snippet is: uwsm check may-start && uwsm select && exec uwsm start default.
COMMANDS
start [--] compositor [args...]
Generate units and start the compositor. Always put -- before compositor flags.select
Interactive (whiptail) picker; saves the default compositor ID.stop [-r [compositor]]
Tear down the session. -r also removes generated units.app [-s a|b|s] [-t scope|service] -- {cmd|entry.desktop[:action]}
Launch an app in app-graphical, background-graphical, or session-graphical slice.finalize [VAR...]
Export compositor-set variables (WAYLAND_DISPLAY, DISPLAY, extras) and notify systemd the compositor is ready.check may-start
Return success only if login-shell autostart conditions are met (tty, graphical.target, no existing session, ...).
INSTALL
CAVEATS
Requires systemd. Do not exit the compositor with its native quit if you want an ordered unit shutdown; use uwsm stop or loginctl. uwsm app is Python-heavy; uwsm-app (optional) is a faster client. Plugins and unit layout can change across versions.
