# How Omarchy Notifies Users About Pending Migrations: Systemd Service and Desktop Alerts Explained

> Learn how Omarchy notifies users about pending migrations using systemd services and desktop alerts. Get timely updates for your Omarchy system.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-05

---

**Omarchy uses a systemd user service called `omarchy-migrate-notify.service` that executes at every graphical login, runs `omarchy-migrate --pending` to detect outstanding migrations, and displays a desktop notification with a clickable action when updates are waiting.**

The **omacum/omarchy** repository implements a seamless notification system for pending system migrations through a combination of systemd user units and command-line utilities. This architecture ensures users are promptly informed about required updates without manual polling, while respecting system locks during active update operations.

## The Systemd User Service Architecture

Omarchy leverages a **user-level systemd service** to trigger migration checks automatically. The unit file `default/systemd/user/omarchy-migrate-notify.service` defines an `ExecStart` command that invokes the `/usr/bin/omarchy-migrate-notify` helper script immediately upon login.

During initial system provisioning, the `omarchy-provision-first-run` script enables this service for all users, ensuring the notification mechanism survives reboots. The service is designed to restart intelligently, waiting for the global update lock to clear before presenting notifications to avoid interrupting ongoing system operations.

## How Pending Migrations Are Detected

At the core of the notification system lies the **`omarchy-migrate --pending`** command. When executed by the notifier script, this command returns a non-zero exit status only when there are outstanding migrations waiting to be applied to the current user environment.

The detection flow works as follows:

1. The systemd unit triggers `omarchy-migrate-notify`
2. The script internally calls `omarchy-migrate --pending`
3. If the command succeeds (indicating pending migrations), the notification is constructed
4. If no migrations are pending, the script exits silently without displaying UI elements

This approach ensures that users receive notifications only when actionable work is required, minimizing notification fatigue.

## Notification Delivery and Content

### Desktop Notification Format

When pending migrations are detected, Omarchy constructs a desktop notification using its internal notification helper (avoiding raw `notify-send` calls). The notification includes:

- **Title**: "Pending Omarchy Migrations"
- **Body**: "Click to run X pending migration(s)." (where X represents the count)
- **Icon**: The large-slot glyph `` (U+F021) for visual consistency with system update indicators

The notification payload includes a clickable action that allows users to launch the migration process directly from the desktop alert.

### Lock-Aware Behavior

The notification system respects the **`omarchy-update.lock`** file to prevent UI spam during active system updates. When this lock is present, the notifier suppresses all migration alerts and enters a wait state. Once the lock releases—indicating the system update has completed—the service resumes and delivers any queued notifications.

This lock-handling logic is verified in the test suite located at [`test/shell.d/migrate-notify-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/migrate-notify-test.sh), which validates that notifications are deferred during locked periods and delivered immediately after lock release.

## Manual Invocation and Compatibility

You can trigger the notification workflow manually for testing or scripting purposes:

```bash

# Manually run the notifier to check for and display pending migrations

omarchy-migrate-notify

# Check migration status silently (returns non-zero if pending)

if ! omarchy-migrate --pending; then
    echo "Migrations are available"
fi

# Inspect the systemd service configuration

systemctl --user cat omarchy-migrate-notify.service

```

For backward compatibility with legacy tooling, Omarchy provides the **`omarchy-update-user-notify`** wrapper script located at `bin/omarchy-update-user-notify`. This hidden compatibility layer simply executes `omarchy-migrate-notify`, ensuring third-party scripts and aliases continue functioning while the underlying implementation has migrated to the new naming convention.

## Summary

- **Systemd Integration**: Notifications are handled by `omarchy-migrate-notify.service`, enabled automatically during first-run provisioning via `omarchy-provision-first-run`.
- **Detection Mechanism**: The system checks for pending work using `omarchy-migrate --pending`, which returns a non-zero status only when migrations are required.
- **Smart Delivery**: Notifications respect the `omarchy-update.lock` file, suppressing alerts during active updates and resuming afterward to prevent interface conflicts.
- **Notification Content**: Users receive a desktop alert titled "Pending Omarchy Migrations" with a clickable action and icon glyph ``.
- **Compatibility**: The legacy `omarchy-update-user-notify` command remains available as a wrapper for the modern `omarchy-migrate-notify` implementation.

## Frequently Asked Questions

### What triggers the Omarchy migration notification?

The notification is triggered by the `omarchy-migrate-notify.service` systemd user unit executing at graphical login. This service runs the `omarchy-migrate-notify` script, which checks for pending migrations via `omarchy-migrate --pending`. When this command indicates outstanding migrations exist, the script generates a desktop notification with the title "Pending Omarchy Migrations."

### How can I check for pending migrations manually without receiving a notification?

Execute `omarchy-migrate --pending` directly from your terminal. This command returns a non-zero exit code if migrations are pending, allowing you to check status in shell scripts without triggering the desktop notification UI. You can verify the result by running `echo $?` immediately after the command.

### Why don't I see a notification during system updates?

Omarchy's notification system respects the global update lock file (`omarchy-update.lock`). When this lock is active—indicating a system update is in progress—the `omarchy-migrate-notify` service suppresses all migration alerts and waits for the lock to release. This design prevents notification spam and potential conflicts during active package operations.

### Where can I customize the notification appearance or behavior?

Configuration is managed through the systemd unit file at `default/systemd/user/omarchy-migrate-notify.service` and the notification logic within `bin/omarchy-migrate-notify`. The icon glyph, title text, and body format are defined in the source code of the notification helper, while the service activation timing and restart policies are controlled via the systemd unit directives.