# How to Build Omarchy from the Repository: Complete Source Compilation Guide

> Build Omarchy from the omacom/omarchy repository with this guide. Compile source code, install dependencies, bootstrap toolchains, and build PKGBUILDs for a complete setup.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-12

---

**To build Omarchy from the repository, clone the `omacom/omarchy` source, install the Arch Linux dependencies listed in `install/omarchy-base.packages`, run `./bin/omarchy-install-dev-env` to bootstrap Rust, Node, Python, and OCaml toolchains, then build the PKGBUILDs from the companion `omarchy-pkgs` repository using `makepkg -si`.**

Omarchy is an Arch Linux-centric desktop configuration framework that compiles into a pair of Arch packages. Building Omarchy from the repository requires compiling Rust binaries, bundling QML-based UI components from `shell/shell.qml`, and packaging configuration templates. This guide walks through the complete build process using the actual source files from the `quattro` branch.

## Repository Structure and Build Components

Understanding the repository layout is essential before compiling. The `omacom/omarchy` repository contains the source code, while the packaging definitions reside in a separate repository.

### Core Source Layout

The root directory contains the following key components:

- **`bin/`** – Build helpers and installation scripts, including `bin/omarchy-install-dev-env` and `bin/omarchy-upgrade-to-quattro`
- **`shell/`** – The Quickshell UI written in QML and JavaScript, with `shell/shell.qml` serving as the main entry point
- **`config/`** – Default user configuration templates that are copied to `~/.config/omarchy/` during setup
- **`install/omarchy-base.packages`** – A manifest listing all required Arch Linux system dependencies
- **`migrations/`** – Version-specific upgrade scripts (e.g., [`migrations/1788848726.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1788848726.sh)) invoked during major updates

### Package Architecture

The actual Arch packages are defined in the companion `omarchy-pkgs` repository. The main source tree maintains the runtime dependency list in `install/omarchy-base.packages`, while the PKGBUILD files handle the compilation of Rust code and the bundling of the Quickshell interface.

## Step-by-Step Build Instructions

Follow these steps to compile Omarchy from the source code on a fresh Arch Linux system.

### 1. Clone the Repository and Checkout the Correct Branch

Begin by cloning the source and switching to the active development branch:

```bash
git clone https://github.com/omacom/omarchy.git
cd omarchy
git checkout quattro

```

### 2. Install System Dependencies

Omarchy requires base Arch packages including Qt 6, multimedia libraries, and systemd utilities. Install them directly from the provided package list:

```bash
sudo pacman -S --needed $(cat install/omarchy-base.packages)

```

### 3. Bootstrap the Development Environment

Execute the environment installer to set up the language toolchains required for compilation:

```bash
./bin/omarchy-install-dev-env

```

According to the source code, this script installs:
- **Rust** (`rustup` and `cargo`) – Used for compiling the `omarchy` binary
- **Node** (`npm`) – Required for Quickshell bar plugins
- **Python** (`uv`) – Powers the build helpers and test suite
- **OCaml** (`opam`) – Needed for optional system agents

### 4. Fetch the PKGBUILD Definitions

The packaging files are stored separately from the main source. Clone the `omarchy-pkgs` repository adjacent to your source tree:

```bash
cd ..
git clone https://github.com/omacom/omarchy-pkgs.git
cd omarchy-pkgs

# Checkout the matching tag or commit for the quattro branch

git checkout <matching-tag>

```

### 5. Build and Install the Packages

Compile both the runtime and development packages using `makepkg`:

```bash
cd omarchy
makepkg -si          # Builds and installs omarchy (runtime)

cd ../omarchy-dev
makepkg -si          # Builds and installs omarchy-dev (optional tooling)

```

The `makepkg` process automatically invokes the build scripts defined in the PKGBUILD, which compile the Rust binary, bundle the QML UI, and install all configuration files under `/usr/share/omarchy/`.

### 6. Initialize User Configuration

After package installation, populate your home directory with the default configuration files:

```bash
omarchy-refresh-config omarchy/shell.json
omarchy-refresh-config omarchy/menu.json

```

This command copies templates from `/usr/share/omarchy/config/` to `~/.config/omarchy/`.

### 7. Launch and Verify the Build

Start the Quickshell UI to confirm the build succeeded:

```bash
omarchy-shell

```

To run the automated verification suite located in the source tree:

```bash
./test/all

```

## Handling Version Upgrades

If you are upgrading from an older Omarchy version, the repository includes migration logic in `migrations/`. The helper script `bin/omarchy-upgrade-to-quattro` executes these migration scripts sequentially to transition your configuration safely from legacy versions to the current `quattro` release.

## Summary

- **Omarchy** is built from the `omacom/omarchy` repository using Arch Linux PKGBUILDs defined in a companion repository.
- **System dependencies** are defined in `install/omarchy-base.packages` and must be installed before compilation.
- **Toolchains** including Rust, Node, Python, and OCaml are bootstrapped via `./bin/omarchy-install-dev-env`.
- **Compilation** occurs through `makepkg -si` in the `omarchy-pkgs` directory, producing installable Arch packages.
- **Configuration** is initialized using `omarchy-refresh-config` to copy templates from `/usr/share/omarchy/` to your home directory.

## Frequently Asked Questions

### What is the difference between the main omarchy repository and omarchy-pkgs?

The `omacom/omarchy` repository contains the source code, scripts, and configuration templates, while `omacom/omarchy-pkgs` contains the PKGBUILD files that define how to compile and package that source into installable Arch Linux packages. You need both to build from source.

### Which programming languages are required to build Omarchy?

You need **Rust** for the core binary, **Node.js** for Quickshell UI plugins, **Python** for build helpers and testing, and optionally **OCaml** for certain system agents. The `./bin/omarchy-install-dev-env` script automates the installation of these toolchains.

### How do I upgrade my Omarchy installation after building from source?

Run the upgrade helper script `bin/omarchy-upgrade-to-quattro` from the updated source tree. This script executes migration scripts stored in `migrations/` to transition your configuration and system state to the new version.

### Where are the default configuration files stored after installation?

Default templates reside in `/usr/share/omarchy/config/` as installed by the PKGBUILD. The `omarchy-refresh-config` utility copies these to `~/.config/omarchy/` where user modifications should be made.