Omarchy Update Pipeline for User Notifications and Orphan Packages

The Omarchy update pipeline orchestrates user notifications and orphan package cleanup through the master script bin/omarchy-update, which sequentially executes omarchy-update-user-notify for desktop alerts and omarchy-update-orphan-pkgs for dependency cleanup after system updates.

The Omarchy operating system manages system maintenance through a structured update pipeline that balances user awareness with automated housekeeping. This article examines the specific components handling user notifications and orphan package removal as implemented in the omacom/omarchy repository, detailing how shell scripts in the bin/ directory coordinate these tasks.

Core Architecture of the Omarchy Update Pipeline

The Omarchy update pipeline follows a strict execution order defined in the master orchestration script. According to the source code in bin/omarchy-update, the pipeline chains multiple specialized utilities to ensure users are informed of pending changes while the system remains free of unused dependencies.

Entry Point: bin/omarchy-update

The bin/omarchy-update script serves as the primary entry point for all system maintenance operations. It invokes sub-commands in a specific sequence to handle different aspects of the update lifecycle, from notification to cleanup.

User Notification Step: omarchy-update-user-notify

Early in the pipeline, bin/omarchy-update-user-notify detects whether new system or package updates are available. When updates exist, the script emits a desktop notification using the helper utility omarchy-notification-send.

The notification includes a concise summary—such as "Omarchy update available – reboot to apply"—along with a clickable action that launches the full update UI by invoking omarchy-update. This ensures users receive immediate visual feedback about pending maintenance without interrupting their current workflow.

Orphan Package Cleanup: omarchy-update-orphan-pkgs

Following the core system package update, the pipeline executes bin/omarchy-update-orphan-pkgs to identify and remove unnecessary dependencies. The script utilizes Pacman’s query command pacman -Qdtq to list packages installed only as dependencies that are no longer required by any installed application.

When orphan packages are detected, the script behavior adapts to the execution context:

• Interactive terminals: The script prompts the user to confirm removal of the listed packages.
• Non-interactive contexts (e.g., cron): The script prints a one-line summary advising the user to run omarchy-update-orphan-pkgs manually.

The actual removal operation uses pacman -Rns wrapped in the omarchy-update-pacman-guard safety utility to prevent accidental deletion of critical system components.

Update Sequence Verification

The exact ordering of these operations is codified in test/shell.d/update-sequence-test.sh, which validates the pipeline through automated testing. The verified sequence executed by bin/omarchy-update is:

1. omarchy-update-user-notify – informs the user of available updates.
2. omarchy-update-system-pkgs – updates core system packages.
3. omarchy-update-orphan-pkgs – cleans up newly orphaned packages.
4. Additional steps including omarchy-update-pkg-prune, omarchy-update-lock, and final status reporting.

This sequencing ensures that notifications occur before any system changes, and orphan cleanup happens only after new packages are fully installed.

Practical Commands for Managing Updates

System administrators can interact with the Omarchy update pipeline through several direct commands:

# Trigger the complete update pipeline including notifications and orphan cleanup

omarchy-update

# Send only the user-facing notification for quick status checks

omarchy-update-user-notify

# Run orphan package detection and removal directly (interactive mode)

omarchy-update-orphan-pkgs

Summary

• The Omarchy update pipeline is orchestrated by bin/omarchy-update, which chains specialized utilities in a strict sequence.
• User notifications are handled by omarchy-update-user-notify using omarchy-notification-send to deliver desktop alerts with clickable actions.
• Orphan packages are identified via pacman -Qdtq and removed through omarchy-update-orphan-pkgs, which adapts its interface for interactive or automated contexts.
• The execution order is validated by test/shell.d/update-sequence-test.sh, ensuring notifications precede updates and cleanup follows installation.
• Safety mechanisms like omarchy-update-pacman-guard protect the system during package removal operations.

Frequently Asked Questions

How does Omarchy notify users about available updates?

Omarchy uses the omarchy-update-user-notify script to check for pending updates and emit desktop notifications via omarchy-notification-send. These alerts include actionable buttons that launch the full update interface, ensuring users are promptly informed without requiring manual checks.

What command identifies orphan packages in Omarchy?

The omarchy-update-orphan-pkgs script queries Pacman using pacman -Qdtq to list packages that were installed as dependencies but are no longer required. This detection runs automatically after system updates to identify candidates for removal.

Is orphan package removal automated or manual in Omarchy?

The behavior depends on the execution environment. In interactive terminal sessions, omarchy-update-orphan-pkgs prompts for confirmation before removing packages. In non-interactive contexts like cron jobs, it logs a summary and defers removal to the user, preventing unattended deletion of potentially wanted software.

Where is the update pipeline sequence defined and tested?

The execution order is defined in bin/omarchy-update and validated by test/shell.d/update-sequence-test.sh. This test ensures the pipeline consistently runs notifications first, system updates second, and orphan cleanup third, maintaining system stability throughout the process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}