How to Install Omarchy (Quattro) on Arch Linux: A Complete Guide

To install Omarchy, clone the basecamp/omarchy repository, switch to the quattro branch, and run sudo ./bin/omarchy-upgrade-to-quattro from the repository root.

Omarchy is an opinionated Arch-based Linux distribution that installs via declarative scripts rather than traditional ISO installers. This guide covers the complete installation process using the Quattro branch, which contains the latest installer scripts and package lists according to the basecamp/omarchy source code.

Prerequisites

Before installing Omarchy, ensure your system meets these requirements:

• A clean Arch Linux base (or any Arch-compatible distribution) with pacman available
• Git to clone the repository from GitHub
• Network access for downloading package repositories and optional third-party assets
• Sudo privileges to execute system-level installation scripts

Step-by-Step Installation

The installation process is deliberately minimal and consists of three main phases: cloning the repository, running the system upgrade script, and executing user-level configuration.

Clone the Repository

First, clone the Omarchy repository and checkout the Quattro branch, which contains the active installer:

git clone https://github.com/basecamp/omarchy.git -b quattro /tmp/omarchy
cd /tmp/omarchy

Alternatively, you can clone to your home directory:

git clone https://github.com/basecamp/omarchy.git -b quattro $HOME/omarchy
cd $HOME/omarchy

Run the Upgrade Script

The single entry point for a full installation is bin/omarchy-upgrade-to-quattro. This script orchestrates the entire setup process:

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

As implemented in the basecamp/omarchy repository, this script performs several critical actions:

• Updates the system keyring and mirrors
• Installs the base Omarchy package set via the helper omarchy-update-system-pkgs
• Executes user-level setup scripts under install/user/
• Generates default configuration files in ~/.config/ using the omarchy-refresh-config pattern

User-Level Configuration Scripts

After the system packages are installed, the installer automatically runs user-side scripts located in the install/user/ directory. These can also be re-run manually if you need to reconfigure specific components:

• install/user/mise.sh – Installs the mise version manager and configures language runtimes
• install/user/theme.sh – Copies the default Omarchy theme files and applies the current theme
• install/user/xcompose.sh – Sets up the XCompose file for custom key bindings

To re-run a specific user script after installation:

bash ./install/user/theme.sh

To refresh a single configuration file after manual edits:

omarchy-refresh-config hypr/hyprland.lua

Post-Install Configuration Options

Beyond the base installation, Omarchy supports specialized deployment scenarios through additional documentation in the manual/ directory.

Dual-Boot Installation

For installing Omarchy alongside another operating system, refer to the detailed guide at manual/51-dual-boot-install.md. This documentation covers partitioning strategies, bootloader configuration, and safe installation procedures when preserving another OS on the same machine.

Unattended Installations

For automated deployments or scripted installs, consult manual/52-unattended-installs.md. This manual describes how to provide a pre-seeded configuration file to the upgrade script, enabling hands-free installations across multiple machines or VM provisioning.

Summary

• Omarchy installs via bin/omarchy-upgrade-to-quattro in the quattro branch of basecamp/omarchy
• Requires only a base Arch system, git, and network connectivity
• The installer updates system packages, then runs user scripts from install/user/ (mise.sh, theme.sh, xcompose.sh)
• Configuration is managed through ~/.config/ with the omarchy-refresh-config utility
• Supports dual-boot and unattended installation modes via documentation in manual/

Frequently Asked Questions

Can I install Omarchy on a non-Arch Linux distribution?

No. Omarchy is specifically built as an Arch-based Linux distribution and depends on pacman for package management. The installer scripts assume an Arch Linux base or derivative. You must start with a clean Arch installation before running the Omarchy installer.

What is the difference between the Quattro branch and other branches?

The quattro branch contains the latest stable installer scripts and package lists for Omarchy. When cloning the repository, you must specifically checkout this branch using -b quattro to ensure you receive the correct installation files and dependency definitions.

Can I re-run individual configuration scripts after installation?

Yes. While bin/omarchy-upgrade-to-quattro runs all user scripts automatically, you can manually execute individual scripts from the install/user/ directory. For example, run bash ./install/user/mise.sh to reconfigure language runtimes, or bash ./install/user/theme.sh to reset theme settings.

How do I update an existing Omarchy installation?

Run the same upgrade script used for installation: sudo ./bin/omarchy-upgrade-to-quattro. This command updates system packages, refreshes the keyring, and re-applies the latest configuration templates. For specific config file updates, use omarchy-refresh-config with the relevant file path.

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