What Is the `omarchy update` Command For? Complete System Update Workflow

The omarchy update command orchestrates a comprehensive, atomic update process that refreshes both the Omarchy environment and all underlying Arch Linux system packages while maintaining safety through snapshots, locks, and automatic cleanup.

The omarchy update command serves as the primary maintenance interface for machines running Omarchy, the Arch Linux-based development environment maintained by Basecamp. According to the source code header in quattro/bin/omarchy-update, the script's explicit purpose is to "Update Omarchy and system packages" (lines 3-5), coordinating a multi-stage workflow that handles everything from pre-flight checks to optional system reboots.

How omarchy update Works

The command executes a carefully sequenced pipeline of operations defined in bin/omarchy-update. Each stage is delegated to specialized helper scripts to ensure modularity and reliability.

Pre-flight Validation and Concurrency Control

Before modifying the system, the script invokes bin/omarchy-update-lock to acquire an exclusive lock, preventing concurrent update instances from interfering with each other. It then runs omarchy-update-requires-free-space to verify that sufficient disk space exists for downloading and installing updates.

Safety Mechanisms and System Snapshots

The workflow prioritizes recoverability by executing omarchy-snapshot create (via bin/omarchy-snapshot) to generate a Btrfs snapshot, creating a rollback point if the update fails. Simultaneously, omarchy-update-stay-awake prevents the system from suspending or sleeping during the potentially long-running operation.

Core Package and Environment Updates

The actual update sequence processes multiple package sources and environments:

1. omarchy-update-dev and omarchy-update-keyring refresh development tools and update cryptographic keyrings.
2. omarchy-update-system-pkgs (defined in bin/omarchy-update-system-pkgs) upgrades all native system packages using pacman.
3. bin/omarchy-migrate runs pending configuration or schema migrations to ensure compatibility with new versions.
4. omarchy-update-aur-pkgs handles updates for packages installed from the Arch User Repository.
5. omarchy-update-mise synchronizes language runtimes and tools managed by the mise version manager.

Cleanup and Finalization

The final phase removes orphaned dependencies via omarchy-update-orphan-pkgs, analyzes operation logs with omarchy-update-analyze-logs, and reports the final status through omarchy-update-status. The script releases wake-locks and, if necessary, triggers a system reboot through omarchy-update-restart.

Usage Examples

Basic Interactive Update

Run the full update workflow with manual confirmation:

omarchy update

Prompts for user confirmation before proceeding with package installations.

Unattended Automatic Updates

Execute updates without interactive prompts using the -y flag:

omarchy update -y

This sets the OMARCHY_UPDATE_UNATTENDED environment variable (lines 24-27 in quattro/bin/omarchy-update), allowing the script to proceed automatically through all stages.

Manual Snapshot Before Updating

While the script attempts automatic snapshots, you can manually create one first:

omarchy snapshot create
omarchy update

Explicitly ensures a rollback point exists at bin/omarchy-snapshot before the update begins.

System-Only Package Updates

To update only system packages without the full Omarchy orchestration:

omarchy-update-system-pkgs

Directly invokes the package updater without locks, snapshots, or migration steps.

Key Implementation Files

The update system is modularized across several scripts in the bin/ directory:

• bin/omarchy-update: The main driver script located at quattro/bin/omarchy-update that coordinates the entire workflow.
• bin/omarchy-update-lock: Implements file-based locking to prevent concurrent update processes.
• bin/omarchy-update-system-pkgs: Performs the actual pacman system package upgrades.
• bin/omarchy-migrate: Executes post-upgrade configuration and schema migrations.
• bin/omarchy-snapshot: Manages Btrfs snapshots for system recovery and rollback capabilities.

Summary

• omarchy update is the centralized command for maintaining both Omarchy and the underlying Arch Linux system.
• The workflow includes safety mechanisms like file locks, free-space checks, and automatic Btrfs snapshots.
• It handles multiple package sources including official repositories, AUR packages, and mise-managed tools.
• The -y flag enables unattended operation by setting OMARCHY_UPDATE_UNATTENDED.
• Migration scripts run automatically to ensure configuration compatibility after upgrades.
• Comprehensive cleanup removes orphaned packages and analyzes logs before completion.

Frequently Asked Questions

Does omarchy update modify only Omarchy or the entire system?

The command updates both. According to the source code header in quattro/bin/omarchy-update, it handles "Update Omarchy and system packages," meaning it refreshes the Omarchy environment configuration, development tools, and all underlying Arch Linux system packages including the kernel and system libraries.

How do I run updates automatically without prompts?

Supply the -y flag when invoking the command:

omarchy update -y

This sets the OMARCHY_UPDATE_UNATTENDED environment variable, causing the script to skip confirmation prompts and proceed through all stages—snapshot creation, package updates, migrations, and cleanup—without user intervention.

Can I rollback if an update breaks my system?

Yes. The omarchy update command automatically creates a Btrfs snapshot via bin/omarchy-snapshot before modifying the system. If the update introduces instability, you can restore the previous system state using the snapshot management tools provided by Omarchy, typically through the omarchy-snapshot command interface.

What is the difference between omarchy update and omarchy-update-system-pkgs?

omarchy update is the full orchestration script that handles locks, snapshots, migrations, AUR packages, and cleanup. omarchy-update-system-pkgs is a specialized helper script (located at bin/omarchy-update-system-pkgs) that only performs the pacman system package upgrade without any of the surrounding safety checks or Omarchy-specific maintenance tasks. Use the latter only when you need to bypass the full workflow.

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