How the Omarchy Update System Works: A Deep Dive into the Atomic Upgrade Pipeline

The Omarchy update system is a self-contained Bash pipeline orchestrated by omarchy-update that guarantees safe, atomic system upgrades through exclusive locking, Btrfs snapshots, and ten distinct specialized phases.

Omarchy's update process transforms a potentially risky Arch Linux rolling upgrade into a deterministic, recoverable operation. Designed for developer workstations that demand both bleeding-edge packages and rock-solid reliability, the system splits every update into isolated phases with clear failure boundaries and automatic rollback capabilities.

How to Trigger an Omarchy Update

The simplest entry point is the omarchy CLI wrapper:

omarchy update

For unattended operation—ideal for cron jobs, CI pipelines, or remote management—add the -y flag:

omarchy update -y

This single flag sets OMARCHY_UPDATE_UNATTENDED=1 and bypasses all interactive prompts.

Phase 1: Logging and Exclusive Lock Acquisition

The omarchy-update script begins by ensuring complete observability. When OMARCHY_UPDATE_LOGGED is unset, the entire command re-executes under script to capture output at /tmp/omarchy-update.log (lines 10–13).

Before any mutation occurs, omarchy-update-lock creates an exclusive lock at $XDG_RUNTIME_DIR/omarchy-update.lock. If another update holds the lock, the current process exits immediately with a user-friendly message (lines 15–17). This prevents the corruption that parallel Pacman operations can cause.

Phase 2: Preconditions and Safety Guards

Two critical checks run before the upgrade begins:

Free-Space Verification

omarchy-update-requires-free-space validates at least 10 GiB of available space on the root filesystem (lines 8–16). Pacman operations can consume substantial temporary space during package decompression and installation.

Force bypass for debugging with:

export OMARCHY_UPDATE_FORCE=1
omarchy update

Unattended Mode Detection

The -y flag sets OMARCHY_UPDATE_UNATTENDED=1 (lines 24–27), which omarchy-update-confirm respects by skipping interactive confirmation (line 28).

Phase 3: Preparation and Snapshot Creation

Three preparatory steps create a clean, protected state:

1. Package cache pruning — omarchy-update-pkg-prune clears Pacman cache and prepares package state (line 31)
2. Btrfs snapshot — omarchy-snapshot creates a filesystem snapshot; failure with exit code 127 (Snapper absent) generates only a warning, while other errors halt the update (lines 36–38)
3. Stay-awake inhibitor — omarchy-update-stay-awake prevents laptop suspension during long-running operations (line 39)

Phase 4: Core Update Execution

The pipeline executes ten specialized scripts in sequence:

Script	Responsibility
omarchy-update-dev	Updates Omarchy-provided development packages
omarchy-update-keyring	Synchronizes Pacman keyring to prevent signature verification failures
omarchy-update-system-pkgs	Executes pacman -Syu for base system upgrade
omarchy-migrate	Runs database and configuration migrations bundled with new packages
omarchy-hook (post-update)	Executes user-defined custom scripts
omarchy-update-aur-pkgs	Rebuilds and upgrades AUR packages from source
omarchy-update-mise	Updates language runtimes managed by mise
omarchy-update-orphan-pkgs	Removes packages no longer required by dependency tree
omarchy-update-analyze-logs	Parses /tmp/omarchy-update.log for failures and surfaces them
omarchy-update-status	Updates the Quickshell UI badge to reflect current state (lines 55–56)

This phased approach isolates failure domains: a broken AUR package cannot corrupt the base system upgrade that preceded it.

Phase 5: Cleanup and Optional Restart

The stay-awake inhibitor stops (line 60) and its EXIT trap removes (line 61). omarchy-update-restart then checks if the kernel or critical components changed, offering a reboot when required (line 63).

Error Handling and Safety Mechanisms

Two defensive patterns protect users:

• Discord-linked error messages — Any uncaught error displays a red-colored message with a link to the community Discord for support (line 19)
• EXIT trap cleanup — The trap on EXIT guarantees the stay-awake lock clears even if the script terminates abnormally (line 20)

Advanced Operations

Check Update Status Manually

omarchy-update-status

This queries whether updates are available, driving the Quickshell UI badge.

Acquire Lock for Custom Operations

omarchy-update-lock run my-custom-script.sh

This leverages the same locking mechanism for ad-hoc maintenance.

Summary

• omarchy-update orchestrates a 10-phase atomic pipeline with exclusive locking and Btrfs snapshots
• Unattended mode (-y) enables fully automated, non-interactive upgrades
• 10 GiB free-space guard prevents disk-full failures during Pacman operations
• Phase isolation ensures AUR build failures cannot corrupt base system state
• Automatic cleanup through EXIT traps and stay-awake inhibitors protects against partial states

Frequently Asked Questions

What happens if an Omarchy update is interrupted?

The EXIT trap (line 20) guarantees cleanup of the stay-awake inhibitor lock regardless of how the script terminates. The Btrfs snapshot created in phase 3 enables manual rollback if the filesystem state is corrupted. The exclusive lock prevents concurrent operations from creating conflicting states.

How does Omarchy handle AUR package build failures?

omarchy-update-aur-pkgs runs after the base system upgrade completes successfully. Because AUR builds execute in a separate phase, a compilation failure cannot roll back or corrupt the core system packages already installed. omarchy-update-analyze-logs surfaces specific build errors for user intervention.

Can I run Omarchy updates automatically via cron?

Yes. The -y flag enables fully unattended operation:

0 2 * * * /usr/bin/omarchy update -y >> /var/log/omarchy-auto.log 2>&1

Set OMARCHY_UPDATE_FORCE=1 if you need to bypass the free-space check in constrained environments, though this is not recommended for production automation.

Where are Omarchy update logs stored?

Complete output captures to /tmp/omarchy-update.log through the script utility when OMARCHY_UPDATE_LOGGED is initially unset. The log persists after completion for inspection by omarchy-update-analyze-logs and manual troubleshooting.

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