Skip to content
Useful utilities
UWSM

UWSM

UWSM

Universal Wayland Session Manager wraps standalone Wayland compositors into a set of Systemd units and provides robust session management including environment, XDG autostart support, bi-directional binding with login session, and clean shutdown.

Please note uwsm is for advanced users and has its issues and additional quirks.

Installation

Arch

uwsm is available in Arch official repositories.

pacman -S uwsm libnewt
Nix/NixOS
{
  programs.hyprland.withUWSM = true;
}

The above option generates a new desktop entry, hyprland-uwsm.desktop, which will be available in display managers.

For more info, read the option.

Warning

If you use the Home Manager module, make sure to disable the systemd integration, as it conflicts with uwsm.

{
  wayland.windowManager.hyprland.systemd.enable = false;
}

Note

For instructions for other distros and manual building, see building and installing section on the project’s page.

Launching Hyprland with uwsm

Note

Pay attention to the warnings in Environment variables, Multi-GPU and Dispatchers sections.

In TTY

GNOME Keyring PAM setup

When launching from a TTY instead of a display manager, some session integrations that display managers normally handle may not be configured. One common example is GNOME Keyring — if pam_gnome_keyring.so is not present in your PAM login configuration, the keyring will not auto-unlock, and applications may prompt you to unlock it manually.

To set this up, add the pam_gnome_keyring.so lines to the PAM configuration file used by your login method (e.g. /etc/pam.d/login for login(1)). Consult your distribution’s documentation for the correct file and syntax. For example, on Arch Linux:

#%PAM-1.0

auth       requisite    pam_nologin.so
auth       include      system-local-login
-auth      optional     pam_gnome_keyring.so
account    include      system-local-login
password   include      system-local-login
-password  optional     pam_gnome_keyring.so    use_authtok
session    include      system-local-login
-session   optional     pam_gnome_keyring.so    auto_start

Display managers (GDM, SDDM, etc.) typically include this PAM configuration already. This step is only needed for console-based (TTY) login.

To launch Hyprland with uwsm, add this code in your shell profile.

if uwsm check may-start && uwsm select; then
    exec uwsm start default
fi

This will bring up the uwsm compositor selection menu after you log into tty1. Choose the Hyprland entry and you’re good to go.

If you want to bypass compositor selection menu and launch Hyprland directly, use this code in your shell profile, instead.

if uwsm check may-start; then
    exec uwsm start hyprland.desktop
fi

Using a display manager

If you use a display manager, choose the Hyprland (uwsm-managed) entry in the display manager selection menu.

Launching applications inside session

The concept of a session managed by Systemd implies also running applications as units. Uwsm provides a helper to do it. Running applications as child processes inside compositor’s unit is discouraged.

Prefix application startup commands with uwsm app --. It also supports launching Desktop Entries by IDs or paths. See man uwsm or uwsm app --help.

Faster alternatives are:

  • uwsm-app: a shell client working with on-demand daemon, optional part of uwsm.
  • app2unit: pure shell alternative, file opener, usually ahead on features.
  • runapp: C++ alternative, even faster, features may vary.

Autostart

XDG Autostart is handled by systemd, and its target is activated in the uwsm-managed session automatically. User services usually require graphical-session.target to be activated by any method on this page.

Some applications provide native systemd user units to be autostarted with. Those might need to be enabled explicitly via systemctl --user enable [some-app.service]. Or, in case the unit is missing [Install] section, enabled more directly: systemctl --user add-wants graphical-session.target [some-app.service]. Also ensure the unit has After=graphical-session.target ordering (it can be added via drop-in).

For example, instead of having hl.exec_cmd("hyprpaper") in your config, simply run systemctl --user enable hyprpaper.service once and have systemd launch it for you from now on.

More autostart-related examples and tricks can be found here.

Notes

It is advised to export the AQ_DRM_DEVICES variable inside ~/.config/uwsm/env-hyprland, instead. This method ensures that the variable is properly exported to the systemd environment without conflicting with other compositors or desktop environments.

export AQ_DRM_DEVICES="/dev/dri/card0:/dev/dri/card1"

There is no need to explicitly set XDG environment variables, as uwsm sets them automatically.

Avoid placing environment variables in the hyprland.lua file. Instead, use ~/.config/uwsm/env for theming, XCursor, NVIDIA and toolkit variables, and ~/.config/uwsm/env-hyprland for HYPR* and AQ_* variables. The format is export KEY=VAL.

export XCURSOR_SIZE=24

See uwsm readme for additional information.

Avoid using the Hyprland exit dispatcher or terminating the Hyprland process directly, as exiting Hyprland this way removes it from under its clients and interferes with ordered shutdown sequence, causing a forced shutdown. Use uwsm stop (or other variants) which will gracefully bring down graphical session (and login session bound to it, if any). If you experience problems with units entering inconsistent states, affecting subsequent sessions, use loginctl terminate-user "" instead (terminates all units of the user).

NixOS UWSM

If you’re using the NixOS module with UWSM (programs.hyprland.withUWSM = true), you can set environment variables like this:

home.nix
{
  xdg.configFile."uwsm/env".source = "${config.home.sessionVariablesPackage}/etc/profile.d/hm-session-vars.sh";
}
Last updated on
Hypr ecosystem