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

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

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:

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:

./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:

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:

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:

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:

omarchy-shell

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

./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.

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