How the Omarchy Update Process Pipeline Works: A Complete Technical Guide

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, 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 <stable|rc|edge|dev>. 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:

omarchy update

Execute a non-interactive update suitable for scripting or automation:

omarchy update -y

Force an update despite low disk space:

OMARCHY_UPDATE_FORCE=1 omarchy update

Bypass the pacman guard for emergency direct package management:

sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman -Syu

Check for available Omarchy updates manually:

omarchy-update-available

Run pending migrations for the current user without a full system update:

omarchy-migrate --pending

Analyze the last update session for errors:

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 <channel> 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 (<hash>) rather than a package version number.

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