What Is the Main Purpose of the Omarchy Project?

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. Common operations include:

Launch the desktop shell:

omarchy launch-shell

Refresh a user configuration file (e.g., Hyprland’s hyprland.lua):

omarchy refresh-config hypr/hyprland.lua

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

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

Update all installed plugins:

omarchy plugin update

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

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.

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