# How Omarchy Handles AUR Packages: Command Architecture and Helper Integration > Omarchy seamlessly manages AUR packages with wrapper commands, integrating with helpers like yay and paru for consistent installation, updates, and migration. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: architecture - Published: 2026-09-03 --- **Omarchy treats Arch User Repository (AUR) packages as first-class citizens through dedicated wrapper commands that detect and delegate to standard AUR helpers like yay or paru, ensuring consistent installation, updates, and migration handling across the system lifecycle.** Omarchy provides a streamlined interface for managing AUR packages on Arch Linux by abstracting helper complexity into unified commands. This article examines how the `omacom/omarchy` repository implements AUR package handling through its specialized dispatcher architecture, safety hooks, and integration with system migrations according to the source code. ## Core AUR Management Commands Omarchy exposes two primary commands for AUR operations that function as symbolic links to the central dispatcher in `bin/omarchy`. These commands handle the complete lifecycle of AUR packages from installation through updates. ### Installing AUR Packages with omarchy-pkg-aur-add The `omarchy-pkg-aur-add` command installs AUR packages by first validating the presence of a compatible AUR helper, then delegating the build and install process. When invoked, the script checks for available helpers such as **yay**, **paru**, or **trizen**, and executes the appropriate install command (e.g., `yay -S `). This command appears in the default-apps test suite at [`test/shell.d/default-apps-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/default-apps-test.sh), where it verifies that the helper detection logic works correctly during fresh installations. The implementation ensures that **pacman hooks** and Omarchy's internal state remain consistent throughout the installation process. ```bash # Install an AUR package (e.g., Brave browser) omarchy-pkg-aur-add brave-origin-bin ``` ### Updating AUR Packages with omarchy-update-aur-pkgs The `omarchy-update-aur-pkgs` command updates all installed AUR packages in a single batch operation. It retrieves the list of foreign packages using `pacman -Qm` and passes them to the configured AUR helper with the `-Syu` flag, handling conflicts using the same resolution logic as standard `pacman -Syu` operations. This command is integrated into the system update pipeline as shown in [`test/shell.d/update-sequence-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/update-sequence-test.sh), positioned after `omarchy-migrate` and before `omarchy-update-restart`. The migration script at [`migrations/1784510887.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1784510887.sh) also demonstrates this command's role in maintaining system consistency during automated updates. ```bash # Update all installed AUR packages omarchy-update-aur-pkgs ``` ## Architectural Implementation Omarchy's AUR handling relies on a sophisticated dispatcher pattern that isolates AUR-specific logic while reusing generic package management infrastructure. ### Unified Command Dispatcher All Omarchy package commands share the central dispatcher located at `bin/omarchy`. The dispatcher examines the `$0` variable (its own filename) to determine which subroutine to execute, allowing `omarchy-pkg-aur-add` and `omarchy-update-aur-pkgs` to exist as symbolic links pointing to the same script. This design keeps AUR logic modular while ensuring consistent error handling and logging across all package operations. ### AUR Helper Detection and Validation At startup, the dispatcher queries the system for known AUR helpers. If no helper is detected, the command fails with a clear error message prompting the user to install yay, paru, or another supported tool. This validation step is exercised by the test suite in [`test/shell.d/default-apps-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/default-apps-test.sh) to ensure graceful failure when dependencies are missing. ### Safety Hooks and System State Before performing any AUR operation, Omarchy runs its standard pacman pre-hooks including `omarchy-migrate` and `omarchy-hook-install` to maintain system consistency. The update sequence follows a strict pipeline: migration checks run first, followed by hook installation, then AUR package updates, and finally the restart step. This sequencing prevents partial updates that could leave the system in an inconsistent state. ```bash # Typical update sequence as implemented in the test suite omarchy-migrate omarchy-hook omarchy-update-aur-pkgs omarchy-update-restart ``` ## AUR Integration in System Migrations Omarchy uses AUR packages within automated migration scripts to ensure idempotent system configuration. The migration file [`migrations/1784510887.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1784510887.sh) demonstrates adding AUR packages during system updates by calling `omarchy-pkg-aur-add` directly. This approach ensures that fresh installations and migrating systems use identical logic for AUR package handling, including helper detection and error management. ```bash # Example migration script content from migrations/1784510887.sh #!/usr/bin/env bash # Add Brave from the AUR as part of the migration omarchy-pkg-aur-add brave-origin-bin ``` ## Testing Coverage for AUR Operations The AUR handling implementation includes comprehensive test coverage across multiple scenarios. The [`test/shell.d/default-apps-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/default-apps-test.sh) file validates the installation workflow, while [`test/shell.d/update-sequence-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/update-sequence-test.sh) verifies the correct placement of AUR updates within the system maintenance pipeline. Additional testing in [`test/shell.d/upgrade-to-quattro-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/upgrade-to-quattro-test.sh) ensures that AUR update steps remain present when upgrading between Omarchy versions, covering edge cases such as disk-space constraints and pacman lock file handling. ## Summary - **Omarchy provides two dedicated commands** (`omarchy-pkg-aur-add` and `omarchy-update-aur-pkgs`) that wrap standard AUR helpers for consistent package management. - **The central dispatcher** at `bin/omarchy` routes all package commands through a unified entry point that examines `$0` to determine the appropriate subroutine. - **AUR helper detection** validates the presence of yay, paru, or trizen before executing operations, failing gracefully with user guidance if none are found. - **Safety hooks** ensure AUR operations run within the proper sequence of migration checks and system state validation. - **Migration scripts** leverage the same AUR commands as interactive usage, ensuring identical behavior during automated system updates. ## Frequently Asked Questions ### What AUR helpers does Omarchy support? Omarchy detects and supports standard AUR helpers including **yay**, **paru**, and **trizen**. The dispatcher queries for available helpers at runtime, and if none are found, the command exits with an error message directing the user to install one of these tools before proceeding. ### How does Omarchy ensure AUR updates don't break the system? Omarchy positions AUR updates within a strict pipeline that runs `omarchy-migrate` and `omarchy-hook-install` before executing `omarchy-update-aur-pkgs`. This sequence ensures system state consistency before modifying packages, and the command uses `pacman -Qm` to accurately target only foreign packages while respecting pacman's conflict resolution during the upgrade process. ### Can I use Omarchy's AUR commands in custom scripts? Yes, the `omarchy-pkg-aur-add` command is designed for use in both interactive shells and automated scripts. The migration file at [`migrations/1784510887.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1784510887.sh) demonstrates this pattern, showing how the command can be invoked within bash scripts to ensure AUR packages are installed with the same helper detection and safety checks used during normal system operation. ### Where does Omarchy track which AUR packages are installed? Omarchy does not maintain a separate tracking database for AUR packages. Instead, it relies on pacman's native foreign package list obtained via `pacman -Qm`. This approach ensures that `omarchy-update-aur-pkgs` always operates on the authoritative system state rather than a potentially stale cache.