How Omarchy Is Installed on Arch Linux: Complete Installation Pipeline

Omarchy installs on Arch Linux through an automated, Bash-based wizard delivered via a full-stack ISO that handles partitioning, encryption, package installation, and hardware-specific configuration in seven distinct steps.

Omarchy is a full-stack Arch Linux distribution that automates the entire installation workflow through a sophisticated Bash-based installer. Unlike manual Arch installations requiring step-by-step partition creation and package selection, Omarchy provides a curated desktop environment—built on Hyprland and quickshell—through an idempotent installation pipeline defined in the basecamp/omarchy repository.

The Seven-Step Omarchy Installation Pipeline

The installation process is orchestrated by the Omarchy installer, which executes the following high-level steps backed by concrete scripts in the repository.

Step 1: Partitioning and LUKS Encryption

The installer prompts the user to select a target disk, then creates a GPT layout and—by default—configures LUKS encryption for the root partition. This interactive disk setup is handled by install/user/first-run/welcome.sh, which captures user preferences for layout and encryption before proceeding to filesystem creation.

Step 2: Base Package Installation

A curated list of core packages is installed from Arch repositories and the Omarchy package mirror. The canonical package list lives in install/omarchy-base.packages, defining the minimal desktop stack including the Hyprland compositor (hyprland, hyprpicker, hyprsunset), the quickshell UI daemon, and essential CLI tooling.

Step 3: System-Wide Configuration

After base packages are installed, install/config/all.sh serves as the master entry point for applying system-wide settings. This script sources smaller, focused configuration scripts such as install/config/firewall.sh for network rules and install/config/enable-services.sh for systemd unit activation, ensuring the base system is hardened and services are properly enabled.

Step 4: Hardware-Dependent Hooks

The installer detects specific hardware components—CPU, GPU, laptop model—and executes only relevant fix scripts under install/hardware/. For example, install/hardware/intel/video-acceleration.sh installs VA-API packages for Intel graphics acceleration, while install/hardware/asus-rog.sh applies ASUS-specific power management settings.

Step 5: First-Run User Setup

User-level personalization is handled by scripts in install/user/first-run/. The enable-user-units.sh script configures the default keyring, sets up GTK themes, and enables systemd user units. This step also handles optional component installation, such as configuring a Windows VM or enabling Tailscale networking.

Step 6: Migration and Snapshot Creation

If upgrading from an older Omarchy edition, migration scripts in migrations/—such as migrations/1785608166.sh—execute to reconcile configuration files and package sets with the current version. Snapper snapshots are created automatically, enabling safe rollbacks if the update introduces issues.

Step 7: Finalization and Edition Marking

Once all scripts succeed, the installer writes the /etc/omarchy-edition marker file—used by future migration checks—and reboots the system into the freshly installed environment.

Idempotent Design and Safety Guarantees

The Omarchy installer is deliberately idempotent: running it a second time (for example, after a failed installation) will skip already-installed packages and re-apply only missing configuration steps. This safety mechanism is enforced by helper functions in install/helpers/logging.sh and guard checks distributed throughout the installation scripts.

Post-Installation Management Commands

After the system boots, manage your Omarchy installation using these CLI tools:

# Install an optional AUR package (e.g., Firefox)

omarchy pkg add firefox

# Refresh specific configuration files to latest defaults

omarchy refresh-config hypr/hyprland.lua

# Apply system updates and pending migrations

omarchy update

# Re-install core Omarchy packages (useful after manual purging)

omarchy reinstall

# Enable and start the user update timer

systemctl --user enable omarchy-update.timer
systemctl --user start omarchy-update.timer

Key Installation Files and Scripts

• install/omarchy-base.packages — Defines the core package set shipped on the ISO, including the Hyprland compositor stack and quickshell.

• install/config/all.sh — Master configuration script that applies system-wide settings after base package installation.

• install/user/first-run/*.sh — Collection of user-level setup scripts handling keyring initialization, theme configuration, and service enablement.

• install/hardware/**/*.sh — Hardware detection scripts and per-model fixes for GPU acceleration, audio firmware, and laptop-specific power settings.

• migrations/*.sh — Version-to-version migration scripts that adjust configs and package selections during system updates.

• bin/omarchy-update — CLI wrapper that drives the update workflow, invoking migrations and pacman.

• bin/omarchy-reinstall — Utility to restore the default package set and configuration files.

Summary

• Omarchy is delivered as a full-stack Arch Linux ISO with an automated Bash-based installation wizard.
• The installation follows a seven-step pipeline: partitioning, base packages, system configuration, hardware hooks, user setup, migrations, and finalization.
• The installer is idempotent, allowing safe re-execution without duplicating installed packages.
• Hardware-specific fixes are automatically applied based on detected CPU, GPU, and laptop model.
• Migration scripts and Snapper snapshots ensure safe upgrades and rollback capabilities between Omarchy editions.

Frequently Asked Questions

Can Omarchy be installed on top of an existing Arch Linux installation?

No. Omarchy is designed as a complete distribution delivered via ISO. The installation process formats the target disk and installs the curated omarchy-base.packages set, making it unsuitable for layering atop existing Arch installations without data loss.

What happens if the Omarchy installation is interrupted or fails?

Because the installer is idempotent, you can safely restart the installation process. The scripts in install/helpers/logging.sh track completed steps, causing subsequent runs to skip already-installed packages and resume from the point of failure.

How does Omarchy handle different hardware configurations?

During installation, the wizard detects your hardware profile and executes specific scripts from the install/hardware/ directory. For instance, systems with Intel graphics automatically receive VA-API acceleration packages via install/hardware/intel/video-acceleration.sh, while ASUS ROG laptops receive specific power management settings.

How are system updates managed after installing Omarchy?

Use the omarchy update command, which invokes bin/omarchy-update. This utility applies pending pacman updates, executes version-specific migration scripts from the migrations/ directory, and creates Snapper snapshots before changes are finalized, ensuring you can rollback if issues occur.

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