# Purpose of uwsm in Omarchy Desktop Session Management: A Complete Technical Guide

> Discover the purpose of uwsm in Omarchy's desktop session management. Learn how uwsm bootstraps Wayland, manages session variables, and launches apps for a robust desktop experience.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-24

---

**`uwsm` (User Wayland Session Manager) serves as the backbone of Omarchy's desktop session handling, bootstrapping the Wayland environment, importing session variables into systemd, and providing the `uwsm-app` wrapper for launching graphical applications under controlled cgroups.**

Omarchy, the innovative Linux desktop distribution from Basecamp, relies on `uwsm` to bridge the gap between the Hyprland compositor and the systemd user session. As a Wayland-specific session manager, `uwsm` ensures that critical environment variables like `WAYLAND_DISPLAY` are available before any graphical target runs. This article examines how `uwsm` functions within the `basecamp/omarchy` codebase, referencing specific implementation files and launch sequences.

## Bootstrapping the Wayland Session

Omarchy initiates its Hyprland session through `uwsm`, which handles environment setup before the compositor starts drawing windows.

### Entry Point in the Desktop File

The session launches from `default/wayland-sessions/omarchy.desktop`, which invokes `uwsm` with specific flags to manage the Wayland display and environment:

```bash
Exec=uwsm start -g -1 -e -D Hyprland hyprland.desktop

```

This command tells `uwsm` to start Hyprland while managing the session lifecycle and ensuring proper exit code handling.

### Environment Import Guarantees

Before `graphical-session.target` is reached, `uwsm` imports the session environment—including `WAYLAND_DISPLAY` and `XDG_*` variables—into the user-systemd manager. The test suite in [`test/shell.d/systemd-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/systemd-test.sh) verifies this behavior, confirming that any user service started by Omarchy receives a complete graphical environment context. This prevents race conditions where services might start before the Wayland display is ready.

## The uwsm-app Launch Wrapper

Omarchy uses `uwsm-app` as a unified wrapper for launching graphical applications, ensuring they inherit the correct session environment and are placed in the proper control group.

### Detached Process Launching

Throughout the Omarchy codebase, launch scripts like `bin/omarchy-launch-browser` execute graphical commands using `setsid uwsm-app --` to detach processes from their callers:

```bash
setsid uwsm-app -- nautilus --new-window "$HOME/Documents"

```

This pattern ensures that applications run independently of the launching terminal and retain the session environment variables imported by `uwsm`.

### Consistent Cgroup Placement

Every process launched via `uwsm-app` ends up in `app.slice/app-*.scope`, enabling uniform resource tracking and OOM handling. The configuration in [`default/systemd/user/app.slice.d/10-oomd.conf`](https://github.com/basecamp/omarchy/blob/main/default/systemd/user/app.slice.d/10-oomd.conf) documents this behavior, allowing systemd's OOM daemon to manage application memory limits consistently across the desktop session.

## Integration with Systemd User Services

Omarchy's background services rely on `uwsm` as a dependency bridge for Wayland-aware operations.

### Service Dependencies

The `omarchy-fcitx5.service` unit demonstrates this integration, explicitly declaring a dependency on `uwsm`:

```ini
[Unit]
Description=My Wayland-aware service
After=uwsm.service
Wants=uwsm.service

[Service]
ExecStart=uwsm-app -- my-binary --flag

```

Services that need to open terminals or display dialogs use `uwsm-app` to ensure they connect to the correct Wayland display. This architecture allows input methods, notification daemons, and crash watchers to function reliably within the graphical session.

## Per-User Configuration via env.d

`uwsm` provides a structured environment variable system through `default/uwsm/env.d/10-omarchy`, which supplies default session variables. Users can override these defaults by creating files in `~/.config/uwsm/env.d/`, following the numbering convention:

```bash

# ~/.config/uwsm/env.d/99-custom

export MY_VAR="hello"

```

Omarchy's default configuration sources these files in order, allowing for persistent customizations that apply to every session launch without modifying system files.

## Practical Implementation Examples

The following patterns appear throughout the Omarchy source for common operations:

```bash

# Start the Omarchy Hyprland session (handled by a .desktop file)

uwsm start -g -1 -e -D Hyprland hyprland.desktop

# Launch a graphical app via the wrapper (used by many Omarchy commands)

setsid uwsm-app -- nautilus --new-window "$HOME/Documents"

# Define a custom environment variable for the session

# ~/.config/uwsm/env.d/99-custom

export MY_VAR="hello"

# A user-systemd service that needs Wayland display

# ~/.config/systemd/user/my-service.service

[Unit]
Description=My Wayland-aware service
After=uwsm.service
Wants=uwsm.service

[Service]
ExecStart=uwsm-app -- my-binary --flag

```

## Summary

- **`uwsm`** bootstraps the Omarchy Hyprland session and imports `WAYLAND_DISPLAY` into the systemd user manager before `graphical-session.target`.
- **`uwsm-app`** provides a universal wrapper in `bin/omarchy-launch-browser` and related scripts, launching detached GUI programs under `app.slice`.
- **Systemd integration** allows services like `omarchy-fcitx5.service` to depend on `uwsm.service` for reliable Wayland display access.
- **Environment customization** occurs through `default/uwsm/env.d/10-omarchy` and user overrides in `~/.config/uwsm/env.d/`.

## Frequently Asked Questions

### What does uwsm stand for in Omarchy?

`uwsm` stands for **User Wayland Session Manager**. According to the `basecamp/omarchy` source code, it manages the lifecycle of the Wayland session, handling environment variable propagation and application launching for the Hyprland compositor.

### How does uwsm differ from a traditional display manager?

Unlike traditional display managers that merely authenticate and launch a session, `uwsm` actively manages the session environment by importing `WAYLAND_DISPLAY` and related variables into systemd. As implemented in [`test/shell.d/systemd-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/systemd-test.sh), this ensures user services start only after the graphical environment is fully initialized, preventing the race conditions common in traditional X11 or basic Wayland setups.

### Why does Omarchy use uwsm-app instead of direct command execution?

Omarchy uses `uwsm-app` because it guarantees that graphical applications inherit the complete session environment and are placed in the correct `app.slice` cgroup. The `bin/omarchy-launch-browser` script and similar launchers use `setsid uwsm-app --` to detach processes from the calling context while maintaining proper systemd integration and OOM protection as configured in [`default/systemd/user/app.slice.d/10-oomd.conf`](https://github.com/basecamp/omarchy/blob/main/default/systemd/user/app.slice.d/10-oomd.conf).

### Can I customize environment variables for my Omarchy session?

Yes. Omarchy provides default variables through `default/uwsm/env.d/10-omarchy`, but you can create override files in `~/.config/uwsm/env.d/` following the numeric prefix convention (e.g., `99-custom`). These files are sourced during session startup, allowing you to set custom variables that persist across reboots without modifying system configuration files.