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

> Install Omarchy Quattro on Arch Linux with our guide. Clone the repository, switch branches, and run the upgrade command for a smooth setup.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-19

---

**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:

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

```

Alternatively, you can clone to your home directory:

```bash
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:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/install/user/mise.sh)** – Installs the `mise` version manager and configures language runtimes
- **[`install/user/theme.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/theme.sh)** – Copies the default Omarchy theme files and applies the current theme
- **[`install/user/xcompose.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/xcompose.sh)** – Sets up the XCompose file for custom key bindings

To re-run a specific user script after installation:

```bash
bash ./install/user/theme.sh

```

To refresh a single configuration file after manual edits:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.