How to Deploy Omarchy on Arch Linux: Complete Installation Guide

Deploy Omarchy by cloning the quattro branch to /opt/omarchy on a running Arch Linux system and executing sudo bash install/user/all.sh to automate package installation, hardware detection, and service configuration.

Omarchy is a comprehensive workstation configuration that transforms a minimal Arch Linux installation into a fully-featured desktop environment. Maintained by Basecamp, the deployment process relies on modular shell scripts located in the basecamp/omarchy repository to handle everything from package management to hardware-specific tweaks.

Prerequisites for Deployment

Before you deploy Omarchy, ensure you have a clean Arch Linux base installation with the following:

• A running system with pacman, sudo, and active internet connectivity
• Root privileges or sudo access
• Git installed (or available via pacman -Sy git)

Omarchy does not provide its own ISO; it expects to layer on top of an existing Arch installation—whether fresh or established—converting it into an Omarchy workstation.

Standard Deployment Process

The standard deployment follows a linear path: clone the repository, run the master installer, and reboot into the new environment.

Clone the Omarchy Repository

First, obtain the deployment scripts by cloning the quattro branch directly to /opt/omarchy. According to the source code in install/user/all.sh, this location is expected by subsequent configuration scripts.

sudo pacman -Sy git
sudo git clone https://github.com/basecamp/omarchy.git -b quattro /opt/omarchy
cd /opt/omarchy

Run the Master Installer

Execute install/user/all.sh to orchestrate the entire setup. This script sources multiple sub-scripts to handle distinct configuration phases.

sudo bash install/user/all.sh

Under the hood, all.sh performs the following actions:

• Package Installation – Installs packages listed in install/omarchy-base.packages and install/omarchy-other.packages using pacman and the configured AUR helper
• User Configuration – Copies the config/omarchy tree to ~/.config/omarchy, creates the omarchy user-level systemd directory, and runs omarchy-refresh-config to back up existing dotfiles
• Hardware Transitions – Executes vendor-specific scripts from install/hardware/ (such as install/hardware/asus/fix-rog.sh or install/hardware/fix-intel-video-acceleration.sh) to apply firmware and kernel module fixes
• Service Enablement – Sources install/config/enable-services.sh to enable systemd-oomd, snapper, and the omarchy-update timer
• First-Run Hooks – Registers post-update hooks (like the Voxtype installer) that execute on first boot

Reboot and Verify

After the installer completes, a reboot is mandatory to activate systemd units and load hardware modules. Upon restart, the Omarchy UI (Quickshell) launches automatically, presenting the top bar, workspace layout, and command palette.

sudo reboot

Alternative Deployment Methods

Depending on your infrastructure requirements, you can deploy Omarchy using specialized paths documented in the repository's manual/ directory.

Dual-Boot Installation

To deploy Omarchy alongside another operating system, follow the Dual-Boot Install guidelines in manual/51-dual-boot-install.md. This method creates a separate /boot/omarchy partition entry and preserves your existing bootloader configuration while installing Omarchy's kernel and initramfs to the new location.

Unattended Automated Deployment

For headless or cloud deployments, use the Unattended Installs method documented in manual/52-unattended-installs.md. Set the OMARCHY_INSTALL_USER environment variable before invoking install/user/all.sh, and pre-seed any first-run hooks in install/user/first-run/. The script runs non-interactively and respects the environment configuration for automated provisioning.

Upgrading from Omarchy 3

If migrating from Omarchy 3 to the Quattro release, execute the dedicated upgrade script rather than the standard installer:

sudo /opt/omarchy/bin/omarchy-upgrade-to-quattro

This script creates a system snapshot, refreshes Arch keyrings, updates pacman channels, applies packaged migrations, and finally invokes the standard installer to reach the quattro state.

What the Installer Configures

Understanding the modular architecture helps when customizing or troubleshooting your deployment.

Package Installation

The installer reads package manifests located at install/omarchy-base.packages and install/omarchy-other.packages. It uses the system's pacman Binary to install core dependencies, then leverages an AUR helper for community packages required by the Omarchy desktop environment.

Hardware-Specific Fixes

Hardware detection scripts in install/hardware/ provide targeted fixes for specific vendors. For example, install/hardware/asus/fix-rog.sh applies Republic of Gamers-specific firmware settings, while install/hardware/fix-intel-video-acceleration.sh configures VA-API drivers for Intel graphics. These scripts are idempotent—safe to re-run—and execute only when relevant hardware is detected.

Systemd Services

The install/config/enable-services.sh script enables critical background services:

• systemd-oomd – Out-of-memory daemon management
• snapper – Filesystem snapshot management for BTRFS volumes
• omarchy-update.timer – Scheduled update checks for the Omarchy configuration layer

These services ensure the system remains stable and automatically maintained post-deployment.

Summary

• Deploy Omarchy by cloning the quattro branch to /opt/omarchy and running sudo bash install/user/all.sh
• The master installer handles packages, hardware fixes from install/hardware/, and systemd services via install/config/enable-services.sh
• Reboot immediately after installation to load kernel modules and start the Quickshell UI
• Use omarchy-upgrade-to-quattro for migrating existing Omarchy 3 installations
• Dual-boot and unattended deployments are supported through dedicated manual pages in the repository

Frequently Asked Questions

Can I deploy Omarchy on an existing Arch Linux installation?

Yes. The installer scripts are idempotent and check for existing files or systemd units before creating them, making deployment safe on existing Arch systems. The process in install/user/all.sh backs up existing dotfiles before applying Omarchy configurations, preserving your data while converting the system.

How do I perform a dual-boot deployment with Omarchy?

Follow the instructions in manual/51-dual-boot-install.md, which configures a separate /boot/omarchy directory for Omarchy's kernel and initramfs. This preserves your existing bootloader entries while adding Omarchy as a selectable boot option, allowing you to run Omarchy alongside Windows or other Linux distributions.

Is unattended deployment possible for server environments?

Yes. Set the OMARCHY_INSTALL_USER environment variable and run install/user/all.sh in a non-interactive shell. The script supports cloud-init and other automation frameworks by reading pre-seeded configurations and executing first-run hooks from install/user/first-run/. Detailed instructions are available in manual/52-unattended-installs.md.

What happens if the hardware detection scripts fail?

The hardware scripts in install/hardware/ are designed to exit cleanly if they do not detect compatible hardware. You can manually invoke specific fixes (such as sudo bash install/hardware/asus/fix-rog.sh) after deployment if automatic detection missed your configuration, or re-run the master installer to retry hardware detection after installing additional firmware.

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