# How the Omarchy Update Process Works: End-to-End Orchestration Explained

> Discover how the Omarchy update process works. Learn about orchestrated lock-protected checks, snapshots, upgrades, migrations, and cleanup managed by the omarchy-update command.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-28

---

**The Omarchy update process is orchestrated by the `omarchy-update` command, which coordinates lock-protected pre-flight checks, system snapshots, package upgrades, migrations, and post-update cleanup through a series of specialized helper scripts.**

The Omarchy update process in the `basecamp/omarchy` repository provides a robust, atomic pipeline for maintaining Arch-based systems. Implemented primarily in `bin/omarchy-update`, the script ensures system integrity by enforcing single-concurrency, validating prerequisites, and executing a deterministic sequence of upgrade steps with automatic error recovery.

## The Main Orchestrator

At the heart of the Omarchy update process lies `bin/omarchy-update`, a Bash script that functions as the central coordinator. The script initializes with `set -e` (line 8) to ensure immediate exit on any unchecked error, and establishes a friendly error handler via `trap` on ERR (line 19) that directs users to the community Discord for troubleshooting assistance.

## Step-by-Step Update Execution

### 1. Lock Acquisition and Concurrency Control

Before performing any work, the script invokes `omarchy-update-lock` to obtain an exclusive filesystem lock. If another update is already running, the script aborts immediately with the message `An Omarchy update is already running.` The lock persists for the entire duration of the process, preventing dangerous concurrent modifications to the package database.

### 2. Pre-Flight Safety Checks

The update process validates system readiness through three sequential checks:

- **Free-space guard** – `omarchy-update-requires-free-space` (invoked on line 22) verifies sufficient disk capacity exists for the upgrade.
- **Unattended mode detection** – When passed the `-y` flag, the script sets `OMARCHY_UPDATE_UNATTENDED=1` (line 26) to suppress interactive prompts.
- **User confirmation** – In interactive mode, `omarchy-update-confirm` (line 28) prompts for explicit user approval before proceeding.

### 3. Pre-Update Cleanup and Snapshotting

The script first calls `omarchy-update-pkg-prune` (line 31) to remove unused packages, reducing the snapshot size. It then executes `omarchy-snapshot create` (line 36) to capture a Snapper snapshot of the current system. Failure to create a snapshot (exit code 127) is tolerated with a warning (line 37) rather than aborting the update, ensuring the process continues even if snapshotting is temporarily unavailable.

### 4. System Stability Measures

To prevent interruption during long-running operations, `omarchy-update-stay-awake start` (line 39) inhibits system sleep and suspension. A corresponding stop command executes at line 60 upon completion, with an additional EXIT trap established at line 20 ensuring cleanup occurs even if the script terminates early due to an error.

### 5. Core Package Operations

The Omarchy update process executes eight sequential maintenance operations:

1. **Developer tools** – `omarchy-update-dev` (line 41) updates development-specific packages.
2. **Keyring refresh** – `omarchy-update-keyring` (line 42) synchronizes the pacman keyring to ensure package signatures validate.
3. **System packages** – `omarchy-update-system-pkgs` (line 47) performs the core pacman upgrade.
4. **Database migrations** – `omarchy-migrate` (line 48) applies Omarchy configuration and database migrations that ship with new packages.
5. **Post-update hooks** – `omarchy-hook post-update` (line 49) executes user-defined custom actions.
6. **AUR packages** – `omarchy-update-aur-pkgs` (line 50) upgrades Arch User Repository packages.
7. **Mise version manager** – `omarchy-update-mise` (line 51) updates the `mise` tool if installed.
8. **Orphan cleanup** – `omarchy-update-orphan-pkgs` (line 52) removes orphaned dependencies left after the upgrade.

### 6. Post-Update Validation

After package operations complete, `omarchy-update-analyze-logs` (line 54) parses pacman logs for warnings or errors, while `omarchy-update-status` (line 55) generates a concise status summary for the user. This dual approach ensures both automated detection of issues and human-readable reporting of the update outcome.

### 7. Finalization and System Restart

The script stops the stay-awake inhibitor (line 60), removes the EXIT trap (line 61), and evaluates whether a reboot is required. If so, `omarchy-update-restart` (line 63) either prompts the user for confirmation or proceeds automatically when running in unattended mode.

## Running Updates Manually

Execute interactive updates using the main command:

```bash

# Interactive update (prompts for confirmation)

omarchy update

```

For automated environments or remote administration, use unattended mode:

```bash

# Unattended update – useful for cron or remote automation

omarchy update -y

```

To protect custom scripts with the same locking mechanism used by the official update process:

```bash

# Manually acquire the lock, run a custom command, then release it

omarchy-update-lock run my-script.sh arg1 arg2

```

## Summary

- The **Omarchy update process** is centralized in `bin/omarchy-update`, which enforces single-concurrency through `omarchy-update-lock` to prevent simultaneous executions that could corrupt the package database.
- **Pre-flight checks** validate disk space via `omarchy-update-requires-free-space` and user intent before `omarchy-update-pkg-prune` optimizes the system and `omarchy-snapshot create` preserves a recovery point.
- The **core update sequence** refreshes developer tools, keyrings, system packages, AUR packages, and the Mise version manager, while applying necessary database migrations and executing user-defined hooks.
- **Post-update validation** analyzes logs for errors and reports status, with automatic handling of system reboots via `omarchy-update-restart` when kernel or critical library updates require a restart.

## Frequently Asked Questions

### What happens if I run omarchy update while another update is running?

The `omarchy-update-lock` script detects the existing lock file and aborts immediately with the message `An Omarchy update is already running.` This prevents race conditions and package database corruption that could occur from concurrent pacman operations.

### How does Omarchy handle insufficient disk space during updates?

Before snapshotting, `omarchy-update-requires-free-space` (invoked on line 22) validates available disk capacity. If insufficient space is detected, the script exits early with a clear error message, preventing partial updates that could leave the system in an inconsistent state.

### Can I automate Omarchy updates without user interaction?

Yes. Passing the `-y` flag enables unattended mode by setting `OMARCHY_UPDATE_UNATTENDED=1` (line 26), which suppresses all confirmation prompts including the final reboot dialog. This configuration is essential for cron jobs, CI/CD pipelines, and remote management via SSH.

### What should I do if the Omarchy update process fails?

The script uses `set -e` (line 8) to halt immediately on errors, and the ERR trap (line 19) provides instructions for seeking help via the community Discord. Additionally, the Snapper snapshot created at line 36 allows you to roll back to the pre-update system state if the upgrade leaves the system unstable.