# How the Omarchy Update Process Pipeline Works: A Complete Technical Guide > Understand the omarchy update process pipeline. This guide details how the `omarchy update` command manages system updates, validation, package upgrades, and migrations securely. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: deep-dive - Published: 2026-09-13 --- **The Omarchy update process pipeline is a coordinated, multi-stage system orchestrated by the `omarchy update` command that locks the update session, validates system state, performs guarded Arch Linux package upgrades, and executes per-user migrations while preventing direct `pacman` usage through an ALPM hook.** The Omarchy update process pipeline ensures safe, repeatable system upgrades for the `omacom/omarchy` distribution. Unlike standard Arch Linux workflows that rely directly on `pacman -Syu`, Omarchy wraps package management in a controlled pipeline that handles logging, locking, free-space validation, and post-update migrations automatically. ## Pipeline Architecture and Design Goals The pipeline is designed around a **single, visible update flow** that coordinates system-level package transactions with user-level configuration migrations. According to the Omarchy source code in [`docs/update-process.md`](https://github.com/omacom/omarchy/blob/main/docs/update-process.md), the architecture achieves four primary objectives: - **Unified orchestration**: The `omarchy update` command serves as the sole public entry point, managing everything from transcript logging to post-update service restarts. - **User-level migrations**: After system packages upgrade, `omarchy-migrate` runs per-user scripts that may require `$HOME` access, DBus sessions, or interactive prompts. - **Guarded package management**: An ALPM pre-transaction hook (`00-omarchy-update-guard.hook`) aborts raw `pacman -Syu` commands unless executed through the Omarchy pipeline or explicitly bypassed. - **State coordination**: Lock files and marker files under `$XDG_RUNTIME_DIR` and `~/.local/state/omarchy/` serialize concurrent runs, track required reboots, and manage free-space thresholds. ## The Blessed Path: Running `omarchy update` The canonical way to trigger the pipeline is through the `omarchy update` command, implemented in `bin/omarchy-update`. This script orchestrates twelve distinct stages, each handled by dedicated helper utilities. ### Pre-Transaction Safety Checks Before modifying system state, the pipeline performs three validation steps: 1. **Logging initialization**: The entire session is wrapped by `script(1)` to capture all output to `/tmp/omarchy-update.log` for later analysis via `omarchy-update-analyze-logs`. 2. **Lock acquisition**: `omarchy-update-lock` creates a per-user lock file at `${XDG_RUNTIME_DIR:-/tmp}/omarchy-update.lock` to prevent overlapping update runs. 3. **Free-space validation**: `omarchy-update-requires-free-space` checks for at least 10 GiB of free space on the root filesystem. If insufficient space exists, the command aborts unless `OMARCHY_UPDATE_FORCE=1` is set. Unless the `-y` flag is provided, the pipeline pauses for user confirmation before proceeding. ### System Package Upgrade Phase Once validated, the pipeline prepares and executes the package transaction: - **Cache pruning**: `omarchy-update-pkg-prune` trims the pacman cache to retain only two versions per package, keeping snapshot sizes minimal. - **Snapshot creation**: If *snapper* is installed, the pipeline creates a filesystem snapshot before mutation. - **Sleep inhibition**: `omarchy-update-stay-awake start` invokes a sleep inhibitor to prevent the system from suspending during the upgrade. - **Guarded transaction**: `omarchy-update-system-pkgs` calls `omarchy-update-pacman`, which executes `pacman -Syu` within a `systemd-run --scope` context. The helper sets `OMARCHY_UPDATE_PACMAN=1` to satisfy the ALPM hook guard. If conflicts occur, `omarchy-update-system-pkgs-when-conflicted` handles resolution. ### Post-Update Actions and Migration After the package transaction completes, the pipeline finalizes the system state: - **Status refresh**: `omarchy-update-status` updates the shell's update indicator widget. - **Sleep release**: `omarchy-update-stay-awake stop` removes the inhibitor. - **Per-user migrations**: `omarchy-migrate` executes pending migration scripts stored in `~/.local/state/omarchy/migrations/` and processes new scripts from the `migrations/*.sh` directory. - **Restart coordination**: `omarchy-update-restart` checks for `~/.local/state/omarchy/reboot-required` or `~/.local/state/omarchy/restart-*-required` markers, prompting for reboots or restarting flagged services as needed. ## Guarding Against Direct Pacman Usage The pipeline enforces the **blessed path** through an ALPM pre-transaction hook installed at `00-omarchy-update-guard.hook`. This hook executes `/usr/bin/omarchy-update-pacman-guard` before any `pacman` transaction. The guard script detects raw `pacman -Syu` invocations and aborts with `AbortOnFail` unless one of two environment variables is present: - `OMARCHY_UPDATE_PACMAN=1`: Set automatically by `omarchy-update-pacman` when executing through the pipeline. - `OMARCHY_ALLOW_DIRECT_PACMAN=1`: An explicit user bypass for emergency maintenance. If the guard aborts, it prints instructions directing the user to run `omarchy update` instead. ## Release Channels and Version Management The Omarchy update process pipeline supports multiple release channels that determine repository sources and update behavior: - **stable**: Production releases using the standard pacman repository. - **rc**: Release candidate builds for pre-release testing. - **edge**: Bleeding-edge builds with recent commits. - **dev**: Local development checkouts linked via symlink. Switch channels using `omarchy-channel-set `. The active channel determines which mirrorlist Omarchy uses and whether it treats the installation as a dev-linked checkout. Check installed versions with `omarchy-version`, which reports either the package version (e.g., `1.2.3`) or development state (e.g., `dev (a1b2c3d)`). The `omarchy-update-available` binary queries the active channel for newer releases and drives the shell widget that alerts users to pending updates. ## Key Binaries and Coordination Files The pipeline relies on a specific filesystem layout for state management and execution: **Coordination Files:** - `${XDG_RUNTIME_DIR:-/tmp}/omarchy-update.lock`: Per-user lock file preventing concurrent updates. - `/tmp/omarchy-update.log`: Complete transcript of the current or most recent update session. - `~/.local/state/omarchy/migrations/`: Storage for per-user migration completion markers. - `~/.local/state/omarchy/reboot-required`: Marker file signaling that a system reboot is necessary. - `~/.local/state/omarchy/restart-*-required`: Marker files indicating specific services require restart. **Core Binaries:** - **`omarchy-update`**: Public entry point orchestrating the full pipeline. - **`omarchy-update-lock`**: Manages the per-user update lock. - **`omarchy-update-stay-awake`**: Controls the sleep inhibitor during transactions. - **`omarchy-update-pacman-guard`**: ALPM hook binary that blocks unauthorized pacman usage. - **`omarchy-update-pacman`**: Executes guard-approved pacman transactions within isolated scopes. - **`omarchy-migrate`**: Runs pending per-user migration scripts after package upgrades. - **`omarchy-update-restart`**: Handles reboot and service-restart notifications. - **`omarchy-update-analyze-logs`**: Parses transcripts for known failure patterns. ## Practical Usage Examples Run the complete update workflow interactively: ```bash omarchy update ``` Execute a non-interactive update suitable for scripting or automation: ```bash omarchy update -y ``` Force an update despite low disk space: ```bash OMARCHY_UPDATE_FORCE=1 omarchy update ``` Bypass the pacman guard for emergency direct package management: ```bash sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman -Syu ``` Check for available Omarchy updates manually: ```bash omarchy-update-available ``` Run pending migrations for the current user without a full system update: ```bash omarchy-migrate --pending ``` Analyze the last update session for errors: ```bash omarchy-update-analyze-logs /tmp/omarchy-update.log ``` ## Summary - The **Omarchy update process pipeline** centralizes system upgrades through the `omarchy update` command, replacing direct `pacman` invocation with a guarded, logged, and coordinated workflow. - **Safety mechanisms** include per-user lock files, free-space checks (10 GiB threshold), sleep inhibition during transactions, and optional filesystem snapshots. - The **ALPM hook** at `00-omarchy-update-guard.hook` enforces the pipeline by aborting raw `pacman -Syu` commands unless `OMARCHY_ALLOW_DIRECT_PACMAN=1` is set. - **Post-update handling** automatically runs per-user migrations via `omarchy-migrate` and manages required reboots or service restarts through marker files in `~/.local/state/omarchy/`. - **Multiple release channels** (stable, rc, edge, dev) allow users to control update velocity using `omarchy-channel-set`. ## Frequently Asked Questions ### What happens if I try to run `pacman -Syu` directly instead of `omarchy update`? The ALPM pre-transaction hook `00-omarchy-update-guard.hook` detects the direct invocation and aborts the transaction. The hook runs `/usr/bin/omarchy-update-pacman-guard`, which checks for the `OMARCHY_UPDATE_PACMAN` environment variable. If missing, it exits with `AbortOnFail` and instructs you to use `omarchy update` instead. You can bypass this by setting `OMARCHY_ALLOW_DIRECT_PACMAN=1`, though this is discouraged as it skips the pipeline's safety checks. ### How much free space is required to run an Omarchy update? The pipeline requires at least **10 GiB** of free space on the root filesystem. The `omarchy-update-requires-free-space` helper checks this threshold before allowing the package transaction to proceed. If your system has insufficient space, the update aborts with an error message. You can override this check by setting the `OMARCHY_UPDATE_FORCE=1` environment variable, though this risks filling the disk during the upgrade. ### Where does Omarchy store information about required reboots or restarts? After updates, Omarchy creates marker files in `~/.local/state/omarchy/` to signal required actions. The file `~/.local/state/omarchy/reboot-required` indicates a full system reboot is necessary, while files matching `~/.local/state/omarchy/restart-*-required` signal that specific services need restarting. The `omarchy-update-restart` binary checks these markers and prompts you accordingly, or you can check them manually before logging out. ### Can I switch between stable and development versions of Omarchy? Yes, Omarchy supports four release channels: `stable`, `rc`, `edge`, and `dev`. Use `omarchy-channel-set ` to switch your active channel. This changes which pacman repository Omarchy targets for updates. The `dev` channel specifically supports symlinked development checkouts, which `omarchy-version` identifies by reporting `dev ()` rather than a package version number.