# Omarchy vs omarchy-settings: Understanding the Two-Package Architecture

> Understand the difference between omarchy and omarchy-settings packages. Discover how this two-package architecture enables clean bootstrapping and independent upgrades for Omarchy.

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

---

**Omarchy splits into `omarchy` (runtime binaries and UI) and `omarchy-settings` (static configuration files) to enable clean bootstrapping, independent upgrades, and parallel stable/dev channel packaging.**

Omarchy is a desktop environment for Arch Linux built around Hyprland and Quickshell. Unlike monolithic distributions, it uses a deliberate two-package architecture that separates executable code from system defaults. Understanding this split is essential for installation, troubleshooting, and contributing to the project.

## What the `omarchy` Package Contains

The **`omarchy`** package provides the **runtime layer** — everything that executes when you run an Omarchy session.

This includes:

- **`bin/omarchy*`** scripts — core command-line tools like `omarchy-upgrade-to-quattro` that manage the environment
- **`shell/`** QML files — the Quickshell-based user interface components
- **Runtime libraries and helper scripts** — code that responds to `omarchy …` invocations

Without this package, no Omarchy processes can start. It is the package you interact with directly after installation.

## What the `omarchy-settings` Package Contains

The **`omarchy-settings`** package provides the **static configuration layer** — files that must exist before the runtime can function.

This includes:

- **Skeleton files under `/etc/skel/`** — default user configurations copied when new accounts are created
- **System-wide templates** — files like `/etc/fastfetch/config.jsonc`, Snapper configurations, and systemd unit files
- **Shared assets** — icons, fonts, and other resources installed to `/usr/share/omarchy/`
- **ALPM hooks** — triggers that run automatically when `omarchy-settings` is upgraded

Every upgrade of `omarchy-settings` resynchronizes these files, ensuring the runtime always finds expected defaults.

## Why Two Packages Instead of One

The separation serves three architectural goals enforced throughout the Omarchy source code.

### 1. Bootstrapping Without Race Conditions

The runtime depends on paths like `/etc/skel/.config/omarchy/` existing before first launch. By packaging defaults separately, the installer lays down required files **before** any Omarchy binary executes. This eliminates "missing configuration" errors during initial setup.

### 2. Independent Upgrade Paths

Configuration fixes and new templates ship faster than core code changes. When `omarchy-settings` upgrades, its PKGBUILD refreshes system defaults without touching binaries. The runtime can then pick up new defaults on next start without requiring a full package reinstall.

### 3. Symmetric Channel Packaging

Both stable and development channels mirror this split. The channel selection logic in `bin/omarchy-channel-set` (lines 51-66) explicitly pairs packages:

| Channel | Runtime Package | Settings Package |
|---------|-----------------|------------------|
| Stable | `omarchy` | `omarchy-settings` |
| Development | `omarchy-dev` | `omarchy-settings-dev` |

This symmetry allows clean switching between channels without configuration drift.

## Installing and Verifying the Packages

### Install Stable Omarchy

```bash

# Set channel to stable (default)

omarchy channel set stable

# Install both required packages

sudo pacman -S --needed omarchy omarchy-settings

```

### Install Development (Edge) Omarchy

```bash

# Switch to edge channel

omarchy channel set dev

# Install development pair

sudo pacman -S --needed omarchy-dev omarchy-settings-dev

```

### Verify Current Installation

```bash
omarchy channel current

```

Output shows the active pair:
- `"omarchy-dev omarchy-settings-dev"` — edge channel active
- `"omarchy omarchy-settings"` — stable channel active

### Resynchronize User Defaults

After `omarchy-settings` upgrades, apply latest skeletons to your user account:

```bash
omarchy reinstall-configs

```

This helper reapplies files from `/etc/skel/` without overwriting customizations.

## Key Source Files Demonstrating the Split

| File | Purpose |
|------|---------|
| [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) | Documents how static defaults ship via `omarchy-settings` |
| `bin/omarchy-channel-set` | Defines package pairs per channel at lines 51-66 |
| `bin/omarchy-upgrade-to-quattro` | Selects between `omarchy-settings` and `omarchy-settings-dev` at lines 716-733 |
| [`test/shell.d/config-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/config-test.sh) | Unit tests verifying both packages install together at lines 120-123 |
| `default/libalpm/hooks/90-omarchy-hyprland-reload-resume.hook` | ALPM hook triggered by `omarchy-settings` updates at lines 5-6 |

These files demonstrate how deeply the two-package architecture is embedded in Omarchy's tooling and testing infrastructure.

## Summary

- **`omarchy`** = runtime binaries, Quickshell UI, and executable tools you invoke directly
- **`omarchy-settings`** = static defaults, skeleton files, and system templates required before first run
- **Both required** — the runtime fails without the settings package's provided paths
- **Channel symmetry** — stable and dev channels each use matched pairs (`omarchy`/`omarchy-settings` or `omarchy-dev`/`omarchy-settings-dev`)
- **Independent upgrades** — configuration refreshes without binary changes, and vice versa

## Frequently Asked Questions

### Can I run Omarchy with only the `omarchy` package installed?

No. The runtime expects files like `/etc/skel/.config/omarchy/` and system templates to exist at startup. Without `omarchy-settings`, these paths are missing and the environment fails to initialize. The test suite in [`test/shell.d/config-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/config-test.sh) explicitly validates that both packages are present.

### What happens when I upgrade `omarchy-settings`?

ALPM hooks in `default/libalpm/hooks/` trigger automatically, resynchronizing system files and optionally reloading components. Your user configuration remains untouched unless you manually run `omarchy reinstall-configs` to pull updated skeleton defaults.

### Why does the development channel use different package names instead of a version flag?

The `-dev` suffix (`omarchy-dev`, `omarchy-settings-dev`) allows stable and development versions to coexist in package management without conflicts. The `omarchy-channel-set` script (lines 51-66) encodes these pairs explicitly, enabling clean channel switching via `omarchy channel set dev` or `omarchy channel set stable`.

### Where do my personal configurations live if system defaults come from `omarchy-settings`?

System defaults populate `/etc/skel/` and `/usr/share/omarchy/`. Your personal configurations override these in `$HOME/.config/omarchy/` and related paths. The `omarchy reinstall-configs` command selectively merges new skeleton changes without destroying your customizations.