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

Clone the Basecamp Omarchy repository, execute the system installer at 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:

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. This script installs essential tools like git, yay, mise, foot, and kitty, and sets up the configuration skeleton:

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:

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:

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:

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

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

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