# Difference Between omarchy and omarchy-settings Packages

> Understand the core difference between omarchy and omarchy-settings packages. Learn how runtime code and default configurations work together in the omarchy desktop environment.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-06

---

**The `omarchy` package contains the live runtime code and executables that power the desktop environment, while `omarchy-settings` contains static default configurations and assets that must be seeded to the system and user home directories before the runtime can function.**

The Omarchy desktop environment for Arch Linux is distributed as two complementary packages that work together but serve fundamentally different purposes. Understanding this separation is essential for system administrators, contributors, and users who need to troubleshoot, customize, or package the software. This guide breaks down the architectural distinction based on the source code in the `omacom/omarchy` repository.

## Core Architectural Split

The `omarchy` and `omarchy-settings` packages represent a deliberate **runtime-versus-seed** architecture common in modern Linux distributions.

### What the omarchy Package Provides

The `omarchy` package is the **execution engine**. It contains everything that runs after a user logs in:

- **Quickshell desktop shell** – QML-based UI components in `shell/`
- **CLI entry points** – `bin/omarchy*` scripts that provide the `omarchy` command group
- **Dynamic libraries** and binaries loaded during a session
- **ALPM hooks** in `default/libalpm/hooks/` that orchestrate system-wide updates

These components expect certain files and directory structures to already exist on the system—files that `omarchy-settings` provides.

### What the omarchy-settings Package Provides

The `omarchy-settings` package is the **configuration seed**. It contains static assets that must be in place *before* the runtime starts:

| Content | Destination Purpose |
|---------|---------------------|
| `config/**` files | Seeded to `/etc/skel/.config/` for new users |
| `default/**` directory | Copied to `/usr/share/omarchy/default/` as system-wide fallbacks |
| `icons/` and desktop entries | Application launchers and theming assets |
| `default/snapper/root` | Snapper template for Btrfs snapshots |
| `etc/fastfetch/config.jsonc` | Default system information display configuration |
| System drop-ins in `etc/**` | Files installed directly to `/etc/` |

According to [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md), this separation ensures that users receive a fully populated `$HOME` and that the system has necessary files before the runtime attempts to use them.

## Installation Order and Dependency Management

The packages are designed to be installed together, but with `omarchy-settings` logically preceding `omarchy`. This sequencing matters because:

1. ALPM hooks in `omarchy-settings` trigger first during updates
2. The runtime assumes defaults exist at startup
3. User home directories are populated from `/etc/skel` before first login

The upgrade mechanism explicitly handles both packages as a pair. In `bin/omarchy-upgrade-to-quattro` (lines 719-736), the script selects the correct settings package variant based on the selected channel:

```bash

# From bin/omarchy-upgrade-to-quattro

# Selects omarchy-settings or omarchy-settings-dev as appropriate

```

```bash

# Switch channels and install the correct package pair

omarchy channel-set stable   # Installs omarchy + omarchy-settings

omarchy channel-set dev      # Installs omarchy-dev + omarchy-settings-dev

```

## Package-Specific Hooks and Update Handling

The `omarchy-settings` package includes **ALPM hooks** that pause and resume Hyprland reloads during updates:

- `default/libalpm/hooks/10-omarchy-hyprland-reload-pause.hook` – suspends desktop refreshes before settings update
- `default/libalpm/hooks/90-omarchy-hyprland-reload-resume.hook` – resumes normal operation after completion

These hooks fire specifically on `omarchy-settings` updates to prevent configuration changes from causing visual glitches or crashes during the transaction.

The update availability checker in [`test/shell.d/update-available-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/update-available-test.sh) (lines 125-137) explicitly scans for `omarchy-settings` lines to ensure default updates are never overlooked, even when the runtime package has no changes.

## Channel Variants and Development Workflow

Both packages have `-dev` variants for the development edge channel:

| Channel | Runtime Package | Settings Package |
|---------|---------------|------------------|
| stable | `omarchy` | `omarchy-settings` |
| dev | `omarchy-dev` | `omarchy-settings-dev` |

The channel system validates correct pairing in [`test/shell.d/channel-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/channel-test.sh) (lines 84-89). Mismatched pairs are rejected to prevent runtime–configuration version skew.

```bash

# Verify installed packages match the active channel

pacman -Q omarchy omarchy-settings

# or for development:

pacman -Q omarchy-dev omarchy-settings-dev

```

## Key Files Illustrating the Separation

| File Path | Purpose |
|-----------|---------|
| [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md) (lines 13-110) | Documents the package separation philosophy |
| `bin/omarchy-upgrade-to-quattro` (lines 719-736) | Channel-aware package selection logic |
| `default/libalpm/hooks/10-omarchy-hyprland-reload-pause.hook` | Pre-transaction hook for settings updates |
| `default/libalpm/hooks/90-omarchy-hyprland-reload-resume.hook` | Post-transaction hook for settings updates |
| [`test/shell.d/update-available-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/update-available-test.sh) (lines 125-137) | Ensures settings updates trigger notifications |
| [`test/shell.d/channel-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/channel-test.sh) (lines 84-89) | Validates package pairing correctness |

## Summary

- **`omarchy`** – Runtime package with Quickshell UI, CLI binaries, and dynamic components loaded during user sessions.
- **`omarchy-settings`** – Seed package with static defaults copied to `/etc/skel`, `/usr/share/omarchy/default/`, and system directories before runtime startup.
- **Installation depends on order** – Settings must be present for the runtime to initialize correctly; ALPM hooks enforce this during updates.
- **Channels maintain pairs** – Stable and dev channels each have matched package variants to prevent version mismatch.

## Frequently Asked Questions

### Can I install omarchy without omarchy-settings?

No. The runtime expects default configurations in `/usr/share/omarchy/default/` and user configurations seeded from `/etc/skel`. Without `omarchy-settings`, the desktop shell will fail to initialize properly and CLI commands may error on missing files.

### What happens if omarchy-settings updates but omarchy does not?

The ALPM hooks in `omarchy-settings` still fire, pausing and resuming Hyprland to apply new defaults safely. The update checker explicitly monitors `omarchy-settings` separately to notify users of configuration changes even when the runtime is unchanged.

### How do I switch from stable to development packages?

Use the channel command: `omarchy channel-set dev`. This atomically replaces both `omarchy` with `omarchy-dev` and `omarchy-settings` with `omarchy-settings-dev`, ensuring version compatibility. The upgrade script in `bin/omarchy-upgrade-to-quattro` handles the underlying package transactions.

### Where are the default configurations actually stored on disk?

System-wide defaults reside in `/usr/share/omarchy/default/`. New users receive copies in their home directory from `/etc/skel/.config/omarchy/` and related paths. The runtime falls back to system defaults when user-specific configurations are absent.