# How omarchy update Works in Omarchy: A Deep Dive into the System Update Orchestrator > Discover how omarchy update performs safe, unattended system upgrades in Omarchy. Learn about its 14-step pipeline, file locking, and automatic conflict resolution. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: deep-dive - Published: 2026-09-08 --- **The `omarchy update` command is a Bash orchestration script that executes a 14-step pipeline to safely upgrade both Omarchy and the underlying Arch Linux system, utilizing file-based locking, automatic conflict resolution, and modular helper binaries to ensure reliable, unattended-capable system maintenance.** The `omarchy update` command serves as the central maintenance interface for the Omarchy desktop environment. Implemented in the `omacom/omarchy` repository as a modular Bash architecture, this command coordinates complex system-wide updates while ensuring data safety through snapshots, preventing concurrent executions via file locking, and handling package manager conflicts automatically. ## The Core Architecture of omarchy update The main orchestrator resides in `bin/omarchy-update`, which coordinates a series of specialized helper scripts located in the `bin/` directory. This modular design isolates distinct concerns—such as locking, logging, and package management—into separate executables, making the system easier to maintain and test. The command is also integrated into the Omarchy menu system via `default/omarchy/omarchy-menu.jsonc`, which launches the update in a floating terminal using `omarchy-launch-floating-terminal-with-presentation omarchy-update`. ## Step-by-Step Execution Flow The update process follows a strict sequence designed to maximize safety and recoverability. ### 1. Concurrency Control via File Locking Before performing any operations, the script invokes `omarchy-update-lock` to acquire a file-based lock using `flock -n` (non-blocking). This guarantees that only one update process runs at a time, preventing race conditions with package manager operations. If the lock is already held, the helper re-executes the command within the lock context. ### 2. Logging and Restart-Safe Execution The first invocation re-executes under the `script` command to capture a complete log at `/tmp/omarchy-update.log`. The script checks for the `OMARCHY_UPDATE_LOGGED` environment variable (lines 10-13 of `bin/omarchy-update`) to skip recursive logging on subsequent runs. This ensures a full audit trail even if the process later `exec`s another binary. ### 3. Pre-Update Validation The pipeline verifies system readiness through two checks: - **Disk space**: `omarchy-update-requires-free-space` aborts early if insufficient free space exists. - **Interactive confirmation**: Unless the `-y` flag is passed, `omarchy-update-confirm` prompts the user via `gum`. The `-y` flag sets `OMARCHY_UPDATE_UNATTENDED=1`, enabling fully automated operation. ### 4. System Preparation Before modifying system packages, the script prepares the environment: - **Cache pruning**: `omarchy-update-pkg-prune` runs `paccache -rk2` to retain only the two most recent versions of each package, freeing disk space. - **Snapshot creation**: `omarchy-snapshot create` generates a system snapshot if Snapper is available; if missing, the update proceeds without error. - **Suspend prevention**: `omarchy-update-stay-awake start` activates a systemd inhibitor to block suspend or hibernate during the update process. ### 5. Core Package Updates The actual upgrade happens in several phases: - **Development tools**: `omarchy-update-dev` updates internal development utilities. - **Pacman keyring**: `omarchy-update-keyring` refreshes the package manager's keyring. - **System packages**: `omarchy-update-system-pkgs` executes `pacman -Syu --noconfirm` with an overwrite rule for `/usr/share/omarchy/*`. - **Conflict resolution**: If pacman reports file conflicts, `omarchy-update-system-pkgs-when-conflicted` automatically removes the offending files and retries, eliminating manual intervention. ### 6. Post-Update Processing After system packages upgrade, the script applies configuration changes and cleans up: - **Migrations**: `omarchy-migrate` applies pending database or configuration migrations. - **Hooks**: `omarchy-hook post-update` executes user-defined post-update scripts. - **AUR packages**: `omarchy-update-aur-pkgs` updates packages from the Arch User Repository. - **Mise tools**: `omarchy-update-mise` updates tools managed by the mise version manager. - **Orphan cleanup**: `omarchy-update-orphan-pkgs` detects and optionally removes packages with no remaining dependents. ### 7. Finalization and Reboot The final phase handles reporting and system restart: - **Log analysis**: `omarchy-update-analyze-logs` parses `/tmp/omarchy-update.log` for errors. - **Status reporting**: `omarchy-update-status` prints a concise summary of the update outcome. - **Reboot prompt**: `omarchy-update-restart` releases the stay-awake inhibitor and offers a system reboot or user session restart. ## Key Design Patterns and Safety Mechanisms Several architectural decisions ensure `omarchy update` remains robust across diverse system states: - **File-based locking**: The `flock -n` implementation in `omarchy-update-lock` guarantees atomic lock acquisition, preventing corruption from overlapping package operations. - **Idempotent logging**: The outer `script` wrapper ensures log capture persists across `exec` calls, providing complete forensic data even if the main script is replaced mid-execution. - **Pacman conflict resolution**: The `omarchy-update-system-pkgs-when-conflicted` helper detects when pacman cannot overwrite Omarchy-owned files and automatically clears the obstruction before retrying. - **Modular architecture**: Each distinct task (pruning, snapshots, stay-awake) lives in its own binary, simplifying unit testing and debugging. ## Usage Examples ```bash # Standard interactive update with confirmation prompt omarchy update # Fully unattended update for automation or scripts omarchy update -y # Force snapshot creation even if Snapper is missing OMARCHY_SNAPSHOT_FORCE=1 omarchy update # Run a custom command within the update lock context omarchy-update-lock run my-custom-script.sh ``` ## Summary - The `omarchy update` command in `omacom/omarchy` orchestrates a 14-step Bash pipeline for system maintenance. - **File-based locking** via `omarchy-update-lock` prevents concurrent update attempts using `flock -n`. - **Restart-safe logging** captures all output to `/tmp/omarchy-update.log` using the `script` command. - The `-y` flag enables unattended mode by setting `OMARCHY_UPDATE_UNATTENDED=1` and bypassing the `gum` confirmation UI. - **Automatic conflict resolution** in `omarchy-update-system-pkgs-when-conflicted` handles pacman file ownership issues without manual intervention. - The process includes safety checks for disk space, optional Snapper snapshots, and a systemd stay-awake inhibitor to prevent suspend during critical operations. ## Frequently Asked Questions ### What happens if I run omarchy update while another update is in progress? The `omarchy-update-lock` helper prevents concurrent executions by using `flock -n` (non-blocking) on a file descriptor. If the lock is already held, the command re-executes through the lock helper, ensuring only one update process runs at a time and preventing race conditions with package manager operations. ### How does omarchy update handle pacman file conflicts? When `pacman -Syu` encounters files in `/usr/share/omarchy/*` that it cannot overwrite, the `omarchy-update-system-pkgs-when-conflicted` helper automatically removes the offending files and retries the operation. This avoids manual intervention during system updates while preserving Omarchy's custom configurations. ### Can omarchy update run unattended in scripts? Yes. Passing the `-y` flag sets `OMARCHY_UPDATE_UNATTENDED=1`, which bypasses the interactive `gum` confirmation prompt in `omarchy-update-confirm`. This enables fully automated updates suitable for provisioning scripts or scheduled maintenance windows. ### Where are omarchy update logs stored? The outermost script execution captures all output to `/tmp/omarchy-update.log` using the `script` command. Subsequent invocations check for the `OMARCHY_UPDATE_LOGGED` environment variable to avoid recursive logging. After completion, `omarchy-update-analyze-logs` parses this file for errors and `omarchy-update-status` displays the final results.