# What Is the Main Purpose of the Omarchy Project?

> Discover the Omarchy project a modern Arch-based Linux distro offering a complete desktop with Quickshell compositor unified CLI and plugin architecture for a seamless experience.

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

---

**Omarchy is a modern, opinionated Linux distribution built on Arch that ships a fully-featured desktop environment powered by the Quickshell compositor, designed to provide a cohesive, ready-to-use system managed through a unified CLI and extensible plugin architecture.**

The Omarchy project, hosted at `basecamp/omarchy`, aims to bridge the gap between Arch Linux's flexibility and a polished, sensible user experience. It delivers a single, long-running Quickshell instance that hosts the entire desktop—including the bar, panels, overlays, and menus—while providing a structured configuration model that supports both newcomers and power users.

## Core Purpose and Design Philosophy

According to the project's README (`README.md#L3-L5`), Omarchy is defined as "a beautiful, modern & opinionated Linux distribution." Unlike generic Arch installations that require manual assembly of window managers and tools, Omarchy provides an end-to-end solution where the desktop environment, configuration management, and system utilities are maintained as a unified whole.

The distribution targets users who want the rolling release benefits of Arch without the typical setup friction. It enforces sensible defaults while remaining highly configurable through a layered provisioning system and a plugin-based architecture.

## The Quickshell-Based Desktop Architecture

### Single Long-Running Instance

At the heart of Omarchy is a **single long-running Quickshell instance** that manages all UI components. As documented in `docs/omarchy-shell.md#L3-L6`, this instance hosts the bar, panels, overlays, menus, and background services as plug-ins. This design eliminates the need for separate window managers or disconnected utility processes, reducing resource overhead and configuration complexity.

### Extensible Plugin System

Users can extend or replace desktop components via a plugin manifest. The plugin system allows third-party widgets—such as weather displays or custom system monitors—to integrate seamlessly into the running Quickshell instance without requiring restarts or complex dependency management. Plugins are managed through the CLI, providing a consistent workflow for adding functionality.

## Repository Structure and Package Layout

The Omarchy repository is split into two distinct Arch packages to separate runtime logic from system-wide defaults.

### The `omarchy` Package

This package contains the core runtime binaries, installation and finalization scripts, database migrations, theme assets, and the Quickshell desktop implementation (`docs/file-layout.md#L11-L13`). Key directories include:

- `bin/omarchy` – The central command router that dispatches all `omarchy-*` sub-commands
- `shell/` – Source code for the Quickshell desktop, including UI components and service implementations
- `themes/` – Built-in themes and template files that generate runtime theme assets
- `migrations/` – Per-user migration scripts applied automatically after package upgrades
- `install/` – System-side installation scripts, hardware detection, and finalization logic

### The `omarchy-settings` Package

This complementary package seeds system-wide defaults (e.g., `/etc/skel`, systemd units, and fonts) for new users before the main package is installed (`docs/file-layout.md#L14-L16`). It ensures that first-time users inherit a functional configuration base without manual intervention.

## Layered Configuration Model

Omarchy implements a three-stage provisioning model documented in `docs/file-layout.md#L33-L45` to handle configuration state:

1. **Seed** – Static defaults copied into a new user's home directory during first login
2. **Finalize** – Per-user runtime setup that cannot be handled by `/etc/skel`, executed when the shell first launches
3. **Resync** – A destructive command for existing users to restore defaults, useful for recovery or major version upgrades

This workflow ensures reproducibility across installations while allowing users to override defaults without losing access to upstream improvements.

## Unified CLI Interface

The Omarchy CLI (`omarchy-*` commands) provides a single entry point for system management, routing commands through a router described in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md). Common operations include:

Launch the desktop shell:

```bash
omarchy launch-shell

```

Refresh a user configuration file (e.g., Hyprland’s [`hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hyprland.lua)):

```bash
omarchy refresh-config hypr/hyprland.lua

```

Add a third-party plugin (e.g., a weather widget):

```bash
omarchy plugin add https://github.com/acme/omarchy-weather.git

```

Update all installed plugins:

```bash
omarchy plugin update

```

Run a system update (installs new packages and runs pending migrations):

```bash
omarchy update

```

## Summary

- Omarchy is an opinionated Arch-based Linux distribution delivering a ready-to-use Quickshell desktop
- It runs as a **single Quickshell instance** with UI components loaded as plugins
- The repository splits into **`omarchy`** (runtime) and **`omarchy-settings`** (system defaults) packages
- Configuration follows a **three-stage model**: Seed, Finalize, and Resync
- Management is unified through the **`omarchy`** CLI with sub-commands for shell control, plugins, and updates

## Frequently Asked Questions

### What makes Omarchy different from standard Arch Linux?

Omarchy provides a complete desktop environment out of the box, whereas standard Arch requires manual installation and configuration of window managers, bars, and utilities. It layers a cohesive Quickshell-based interface, a structured configuration workflow, and a unified CLI on top of Arch's package management, targeting users who want rolling release benefits without assembly overhead.

### Can I use Omarchy without the Quickshell desktop?

The distribution is architected around a single long-running Quickshell instance that hosts all UI components. While the underlying Arch system remains accessible, removing or bypassing Quickshell would eliminate the primary desktop environment and require significant manual reconfiguration of the `shell/` and `bin/omarchy` components.

### How does the plugin system work in Omarchy?

Plugins are loaded dynamically into the running Quickshell instance, allowing users to add or replace UI components like menus and widgets via manifest files. The CLI commands `omarchy plugin add`, `omarchy plugin update`, and `omarchy plugin remove` manage these extensions, storing them in user-accessible directories that persist across sessions.

### What happens when I run `omarchy update`?

This command performs a system update that installs new packages from the Arch repositories and executes any pending migration scripts located in the `migrations/` directory. Migrations are applied per-user to ensure configuration files remain compatible with new versions of the `omarchy` package, maintaining state consistency after upgrades.