# How Omarchy Handles System Updates and Migrations: A Complete Technical Breakdown > Learn how Omarchy orchestrates system updates and migrations via a single atomic pipeline. Discover package upgrades, snapshots, lock handling, and migration scripts for a retry-safe workflow. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: deep-dive - Published: 2026-08-31 --- **Omarchy orchestrates system updates and migrations through a single `omarchy-update` pipeline that combines package upgrades, filesystem snapshots, lock handling, and per-user migration scripts into one atomic, retry-safe workflow.** The `omarchy-update` command serves as the central driver for all system maintenance in Omarchy. According to the omacom/omarchy source code, this pipeline ensures that package transactions, filesystem snapshots, and configuration migrations execute in a strict, recoverable order—protecting users from partial updates and configuration drift. ## The Omarchy Update Pipeline: Step-by-Step Execution The update process in `bin/omarchy-update` follows a 14-stage pipeline designed for safety, observability, and re-entrancy. ### 1. Transcript Capture and Re-entrancy Guard Every update session automatically captures all output to `/tmp/omarchy-update.log` by re-executing inside `script(1)`: ```bash # Source: bin/omarchy-update#L10-L13 if [ -z "${OMARCHY_UPDATE_TRANSCRIPT:-}" ]; then export OMARCHY_UPDATE_TRANSCRIPT=1 exec script -q -c "$0 $*" /tmp/omarchy-update.log fi ``` This ensures complete audit trails and simplifies troubleshooting when updates fail. ### 2. Per-User Locking and Free-Space Validation Before any destructive operations, Omarchy establishes safety boundaries: - **`omarchy-update-lock`** — Creates a lockfile at `${XDG_RUNTIME_DIR:-/tmp}/omarchy-update.lock` to prevent concurrent update attempts - **`omarchy-update-requires-free-space`** — Aborts if root filesystem has less than **10 GiB** free ([docs/update-process.md#L143-L146](https://github.com/omacom/omarchy/blob/quattro/docs/update-process.md#L143-L146)) ### 3. Interactive vs. Unattended Modes The `-y` flag controls interaction: ```bash # Interactive (prompts for confirmation) omarchy update # Non-interactive (suitable for automation) omarchy update -y # Sets OMARCHY_UPDATE_UNATTENDED=1 ``` ([source: bin/omarchy-update#L24-L27](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-update#L24-L27)) ### 4. Pre-Snapshot Cache Pruning To conserve snapshot space, `omarchy-update-pkg-prune` runs `paccache -rk2`—keeping only the two most recent versions of each package in the pacman cache ([docs/update-process.md#L121-L122](https://github.com/omacom/omarchy/blob/quattro/docs/update-process.md#L121-L122)). ### 5. Filesystem Snapshot Creation `omarchy-snapshot create` attempts a Snapper snapshot. Notably, exit code 127 (missing Snapper) is **tolerated**, allowing installations on systems without Btrfs: ```bash # Source: bin/omarchy-update#L33-L38 omarchy-snapshot create || { local exit_code=$? [ $exit_code -eq 127 ] || exit $exit_code } ``` ### 6. Sleep Inhibition and Keyring Refresh The pipeline acquires a **systemd inhibitor** via `omarchy-update-stay-awake start` to prevent suspend during updates, then refreshes cryptographic trust: - `omarchy-update-keyring` — Updates Arch and Omarchy keyrings - `omarchy-update-dev` — Fast-forwards development checkouts when present ([bin/omarchy-update#L39-L42](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-update#L39-L42)) ### 7. Package Transaction and Migration Trigger The core system update executes with explicit overwrite rules for Omarchy-managed files: ```bash # Source: bin/omarchy-update#L44-L48 omarchy-update-system-pkgs # Runs: pacman -Syu --noconfirm --overwrite ... omarchy-migrate # Executes pending migrations AFTER pacman completes ``` **Critical ordering**: Migrations run **only after** the package transaction succeeds, ensuring schema and binary compatibility. ## Omarchy Migration System: Idempotent, File-Based Upgrades The migration subsystem in `bin/omarchy-migrate` provides a lightweight, declarative mechanism for evolving system configurations across releases. ### How Pending Migrations Are Detected The script compares migration files against completion markers: ```bash # List pending migrations without applying them omarchy-migrate --pending ``` ([bin/omarchy-migrate#L47-L55](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-migrate#L47-L55)) ### Migration Execution Flow For each pending script in `$OMARCHY_PATH/migrations/*.sh`: 1. **Wait for pacman lock release** — Polls `/var/lib/pacman/db.lck` until absent ([bin/omarchy-migrate#L68-L72](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-migrate#L68-L72)) 2. **Execute with strict error handling** — `bash -euo pipefail` ensures failures halt the pipeline 3. **Record completion** — Empty marker file created at `$HOME/.local/state/omarchy/migrations/