# How to Run Omarchy Locally: Complete Setup Guide for Arch Linux

> Learn how to run Omarchy locally on Arch Linux. Follow this guide to clone the repository, install, configure, and launch the Omarchy UI with simple commands.

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

---

**Clone the Basecamp Omarchy repository, execute the system installer at [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh), initialize configurations with `omarchy refresh-config all`, and launch the Quickshell-based UI using the `omarchy` command.**

Omarchy is a Quickshell-based desktop environment developed by Basecamp and optimized for Arch-based Linux distributions. Running it locally requires installing system dependencies, refreshing default configurations, and launching the main entry point. This guide walks through the exact commands and file locations defined in the `quattro` branch source code.

## Prerequisites

Omarchy is built exclusively for **Arch-based systems** and relies on specific system packages managed through the installer scripts. You will need:

- An Arch Linux or Arch-based distribution (Manjaro, EndeavourOS, etc.)
- `sudo` privileges to install system-wide packages
- `git` to clone the repository (will be installed by the script if missing)

## Step-by-Step Local Installation

### Clone the Repository

Start by cloning the repository and switching to the active `quattro` branch:

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

```

### Install System Dependencies

Run the per-user installation script located at [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh). This script installs essential tools like `git`, `yay`, `mise`, `foot`, and `kitty`, and sets up the configuration skeleton:

```bash
sudo ./install/user/all.sh

```

According to the source code, this script also modifies `/etc/skel` and configures the `$PATH` entry pointing to `/usr/local/bin` where Omarchy binaries are linked.

### Initialize Configuration

Before starting the UI, copy the shipped defaults into your home directory using the refresh command:

```bash
omarchy refresh-config all

```

This command, implemented in `bin/omarchy-refresh-config`, copies default configuration files from the repository's `config/` directory into `~/.config/omarchy/` and creates the runtime state directory at `~/.local/state/omarchy/`.

### Launch the Omarchy Shell

Start the main Quickshell-based UI by running:

```bash
omarchy

```

The `bin/omarchy` entry point starts the Quickshell UI, reads the active theme from `~/.local/state/omarchy/current/`, and registers IPC channels for subsequent commands.

## Where Omarchy Stores Runtime State

Understanding the file layout is critical for debugging and theming:

- **Active configuration** – `~/.config/omarchy/` holds user-specific settings copied during the refresh step
- **Runtime state** – `~/.local/state/omarchy/current/` stores the active theme, background symlinks, and transient UI data
- **Migration tracking** – `~/.local/state/omarchy/migrations/` tracks which per-user migration scripts have already been applied to prevent duplicate execution
- **Notifications** – JSON files under `~/.local/state/omarchy/notifications/` feed the desktop toast system

## Essential Omarchy Commands

After installation, the following helper scripts (located in `bin/` and linked to `$PATH`) are available:

- **`omarchy`** – Launches the main Quickshell UI
- **`omarchy-refresh-config <scope>`** – Copies defaults for specific scopes (`all`, `hypr`, `foot`, etc.)
- **`omarchy-update`** – Runs the full system and user package update pipeline
- **`omarchy-theme-set <name>`** – Switches themes (e.g., `white`, `dark`) and refreshes the UI
- **`omarchy-toggle-touchpad`** – Enables or disables the touchpad via IPC
- **`omarchy-toggle-nightlight`** – Controls the night-light filter
- **`omarchy-toggle-screensaver`** – Starts or stops the screensaver

## Development and Testing Without Full Installation

To experiment with the UI without installing system packages system-wide, run the shell directly from the repository:

```bash
./bin/omarchy-shell

```

This launches the Quickshell QML UI using the same configuration files as the fully installed version, allowing you to test theme changes and IPC commands.

To verify the migration framework and core functionality on a clean checkout, execute the integration test suite:

```bash
./test/all

```

## Summary

- **Clone** the `basecamp/omarchy` repository and checkout the `quattro` branch
- **Install** dependencies via `sudo ./install/user/all.sh`, which configures system packages and `$PATH`
- **Initialize** the environment with `omarchy refresh-config all` to populate `~/.config/omarchy/` and `~/.local/state/omarchy/`
- **Launch** the desktop environment using the `omarchy` command from `bin/omarchy`
- **Develop** using `./bin/omarchy-shell` for rapid testing without full system installation

## Frequently Asked Questions

### Can I run Omarchy on Ubuntu or Debian?

No. Omarchy is explicitly designed for Arch-based systems and relies on `pacman` and Arch-specific package management tools found in [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh). The installer and update scripts assume an Arch Linux environment.

### What should I do if the `omarchy` command is not found after installation?

Ensure the installation script completed successfully and that `/usr/local/bin` is in your `$PATH`. The [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh) script creates symlinks in system directories; you may need to start a new shell session or log out and back in for the `$PATH` changes to take effect.

### How do I reset Omarchy to default settings?

Run `omarchy refresh-config all` to overwrite your current `~/.config/omarchy/` directory with the repository defaults. This command is implemented in `bin/omarchy-refresh-config` and safely restores initial configurations while preserving runtime state in `~/.local/state/omarchy/`.

### Is it safe to run `./bin/omarchy-shell` while the main Omarchy session is active?

Yes. The development shell at `./bin/omarchy-shell` launches independently and uses the same IPC mechanisms and configuration files as the installed version. It is useful for testing UI modifications without disturbing your primary session.