# Omarchy vs Omarchy-Settings: Understanding the Difference Between the Runtime and Configuration Packages

> Understand the difference between Omarchy and Omarchy-settings packages. Discover how the runtime and configuration packages bootstrap your desktop environment.

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

---

**The `omarchy` package contains the executable runtime and Quickshell QML interface, while `omarchy-settings` provides the static configuration skeletons, system templates, and default files required to bootstrap the desktop environment.**

The Omarchy desktop environment from basecamp/omarchy is distributed as two complementary Arch Linux packages rather than a single monolithic install. Understanding the difference between the `omarchy` and `omarchy-settings` packages is essential for proper installation, troubleshooting, and channel management.

## Architectural Overview

Omarchy splits its concerns into **runtime execution** and **static configuration** to solve bootstrapping and upgradability challenges inherent in desktop environment packaging.

### The Runtime Package (`omarchy`)

The `omarchy` package constitutes the **active runtime** of the desktop environment. It ships the executable binaries and live code that powers the user interface.

This package contains:

- `bin/omarchy*` command-line scripts (including `omarchy-upgrade-to-quattro`)
- `shell/` directory with Quickshell QML UI files
- Core libraries and runtime automation scripts
- The executable entry points invoked when you run `omarchy …` commands

You cannot launch a functional Omarchy session without this package installed.

### The Configuration Package (`omarchy-settings`)

The `omarchy-settings` package handles **static defaults** and system-wide templates that must exist on disk before the runtime initializes.

This package installs:

- Skeleton files under `/etc/skel/` for new user home directories
- System configuration files such as `/etc/fastfetch/config.jsonc`
- Snapper templates and systemd unit files
- Icons, fonts, and shared assets under `/usr/share/omarchy/`
- ALPM hooks that trigger configuration resynchronization during upgrades

Install this package **first** (or simultaneously) to ensure the runtime finds its required baseline files.

| Package | Primary Purpose | Key Contents | Installation Priority |
|---------|----------------|--------------|---------------------|
| `omarchy` | Runtime | Executables, QML UI, core scripts | Required for session |
| `omarchy-settings` | Defaults | `/etc/skel` skeletons, system configs, hooks | Install first |

## Why the Separation Exists

The split between `omarchy` and `omarchy-settings` addresses three specific architectural requirements visible in the source code.

### Bootstrapping Dependencies

The runtime expects certain files to exist before it can start. For example, the Quickshell interface references configuration paths under `/etc/skel/.config/` that must be present on disk. By packaging these in `omarchy-settings`, the installer lays down defaults **before** the runtime attempts to read them, preventing "missing file" errors during first boot.

### Independent Upgradability

System defaults evolve independently of core code. When `omarchy-settings` is upgraded, its PKGBUILD copies refreshed templates into `/etc/` and `/usr/share/` without touching the runtime binaries in `/bin/`. This allows rapid delivery of configuration fixes without forcing a full runtime rebuild. The ALPM hooks in `default/libalpm/hooks/90-omarchy-hyprland-reload-resume.hook` automate this resynchronization.

### Channel Packaging Symmetry

Both stable and development channels mirror this two-package structure. As defined in `bin/omarchy-channel-set` (lines 51-66), the stable channel pairs `omarchy` with `omarchy-settings`, while the development channel pairs `omarchy-dev` with `omarchy-settings-dev`. This symmetry ensures consistent behavior regardless of which channel you track.

## Installing and Managing the Package Pair

When installing Omarchy, you must specify both packages to get a working system.

### Installing the Stable Stack

```bash

# Configure the stable channel

omarchy channel set stable

# Install both runtime and defaults

sudo pacman -S --needed omarchy omarchy-settings

```

### Installing the Development Stack

```bash

# Switch to the edge channel

omarchy channel set dev

# Install the development package pair

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

```

### Resynchronizing Configuration

After upgrading `omarchy-settings`, apply the latest skeleton files to your user directory:

```bash
omarchy reinstall-configs

```

### Verifying Your Current Installation

Check which package pair is active on your system:

```bash
omarchy channel current

# Output: "omarchy-dev omarchy-settings-dev" (if on edge)

# Output: "omarchy omarchy-settings" (if on stable)

```

## Key Source Files and Implementation Details

Several files in the basecamp/omarchy repository define and test this package relationship:

- **[`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`** (lines 51-66) – Defines the package pairs for each channel
- **`bin/omarchy-upgrade-to-quattro`** (lines 716-733) – References both `omarchy-settings` and `omarchy-settings-dev` during migration logic
- **[`test/shell.d/config-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/config-test.sh)** (lines 120-123) – Unit tests verifying both packages are installed together
- **`default/libalpm/hooks/`** – Contains ALPM hooks that execute during `omarchy-settings` installs and updates

## Summary

- **`omarchy`** provides the **runtime**: executables, Quickshell QML UI, and command-line tools required to run the desktop session.
- **`omarchy-settings`** provides the **defaults**: skeleton files, system templates, and configuration baseline required before the runtime starts.
- **Bootstrapping** requires `omarchy-settings` to be present first so the runtime finds its required files under `/etc/` and `/usr/share/`.
- **Channel management** pairs these packages symmetrically: stable uses `omarchy` + `omarchy-settings`, while development uses `omarchy-dev` + `omarchy-settings-dev`.
- **Upgrades** to `omarchy-settings` trigger ALPM hooks that resynchronize system defaults without modifying runtime binaries.

## Frequently Asked Questions

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

No. The runtime explicitly depends on configuration files provided by `omarchy-settings`, such as templates in `/etc/skel/` and system-wide settings in `/etc/fastfetch/config.jsonc`. Attempting to start the desktop without these files results in initialization errors because the Quickshell UI expects these paths to exist.

### Will upgrading `omarchy-settings` overwrite my personal configurations?

No. The package updates system-wide defaults under `/etc/` and `/usr/share/`, but your personal configurations in `$HOME` remain untouched unless you explicitly run `omarchy reinstall-configs`. Even then, the tool typically backs up existing files before overlaying new skeleton templates.

### How do I switch from the stable to the development package pair?

Run `omarchy channel set dev` to select the edge channel, then install the development pair with `sudo pacman -S --needed omarchy-dev omarchy-settings-dev`. The channel system ensures you always have matching runtime and configuration packages, as verified by the logic in `bin/omarchy-channel-set`.

### Why do the ALPM hooks only target `omarchy-settings` and not `omarchy`?

The hooks in `default/libalpm/hooks/` handle configuration resynchronization and environment reloading, which only need to occur when static files change. The runtime package `omarchy` contains compiled binaries and QML code that do not require post-installation file manipulation, making hooks unnecessary for that component.