# How the Two-Package Split Between Omarchy and Omarchy-Settings Is Organized

> Discover how Omarchy organizes its two Arch Linux packages omarchy and omarchy-settings. Learn the separation of static defaults and runtime binaries for correct installation.

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

---

**The Omarchy repository builds two distinct Arch Linux packages—`omarchy-settings` and `omarchy`—that separate static system defaults from runtime binaries to ensure correct installation sequencing.**

The **two-package split between omarchy and omarchy-settings** is a deliberate architectural decision in the Omarchy desktop environment. This organization ensures that system-wide defaults exist before users are created, while runtime components install only after a user account is present.

## Package Responsibilities and Installation Order

The repository maintains a strict separation between files needed before user creation and those needed after. This split is documented in [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md), which defines the mental model in lines 8-15 and maps the exact file-to-package relationships starting at line 84.

### The omarchy-settings Package

The `omarchy-settings` package contains all files that must exist **before** the first user is created. According to the file layout documentation, this includes:

- **Skeleton files** under `/etc/skel/` that seed new user homes
- System-wide configuration drop-ins (e.g., `/etc/fastfetch/config.jsonc`, [`/etc/xdg/kitty/kitty.conf`](https://github.com/omacom/omarchy/blob/main//etc/xdg/kitty/kitty.conf))
- Bootloader templates (Limine) and Snapper configuration templates
- Debug binaries like `omarchy-debug` (referenced at line 72 in the file layout)
- Fonts, branding assets, and static defaults

This package installs during the ISO build or first boot, providing the foundation that `useradd -m` copies into `$HOME`.

### The omarchy Package

The `omarchy` package installs **after** a user account exists and depends on `omarchy-settings`. It contains:

- **Runtime binaries** (the `omarchy-*` command suite)
- Installation and finalization scripts
- Per-user migration scripts in `migrations/*.sh`
- The Quickshell desktop environment in `shell/`
- Theme resources and dynamic configuration tools

## Why the Split Is Necessary

The architectural separation addresses four specific technical requirements:

1. **Seeding New Users** – Files under `/etc/skel` copy to new user homes only at creation time. By placing these in `omarchy-settings`, the system guarantees fresh users receive correct defaults without manual intervention.

2. **Pre-User System Configuration** – Resources like bootloader configs, Snapper templates, and system-wide XDG defaults must exist before the Omarchy runtime references them. This ensures functionality even on minimal ISO builds.

3. **Dependency Order** – The `omarchy` package explicitly depends on `omarchy-settings`, enforcing the correct installation sequence and preventing race conditions during setup.

4. **Clean Upgrade Path** – Static defaults update independently from runtime code. This separation eliminates circular dependencies and allows `omarchy-settings` updates without touching active binaries.

## Installation Lifecycle

The two-package architecture follows a three-phase lifecycle managed by specific scripts in the `bin/` directory.

### Seed Phase

During initial system setup, `omarchy-settings` populates `/etc/skel` with default configurations. These static files remain dormant until a user account creation triggers the copy operation.

### Provision Phase

After user creation, `omarchy-provision-user` (part of the `omarchy` package and located in [`install/user/all.sh`](https://github.com/omacom/omarchy/blob/main/install/user/all.sh)) executes. This script handles per-user configurations requiring `$HOME` expansion that cannot exist in the skeleton directory.

### Resync Phase

Existing users refresh configurations using `omarchy-reinstall-configs`. This utility reapplies the current `/etc/skel` tree to an existing home directory, syncing changes made in newer `omarchy-settings` versions.

```bash

# Re-apply default configuration to existing user

omarchy-reinstall-configs

# Show currently installed channel (stable or dev)

omarchy-channel-current

```

## Key Source Files and Scripts

Understanding the repository layout requires familiarity with these specific files:

| File | Purpose |
|------|---------|
| [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md) | Defines the two-package model and maps source trees to installation paths |
| `bin/omarchy-upgrade-to-quattro` | CLI tool selecting the appropriate package pair (stable or dev variants) |
| `bin/omarchy-reinstall-configs` | Implements the Resync phase for existing users |
| `bin/omarchy-provision-user` | Finalizes per-user configuration via [`install/user/all.sh`](https://github.com/omacom/omarchy/blob/main/install/user/all.sh) |
| `default/**` and `etc/**` | Source directories packaged into `omarchy-settings` |
| `migrations/*.sh` | Version-specific migrations running after `omarchy` installation |

## Managing the Package Pair

When upgrading or switching release channels, both packages must update simultaneously to maintain consistency. The upgrade script handles this coordination automatically:

```bash

# Upgrade to latest Quattro development release

omarchy-upgrade-to-quattro --dev

```

This command pulls both `omarchy-dev` and `omarchy-settings-dev`, ensuring the dependency chain remains intact. The `--dev` flag switches to development channels, while omitting it selects stable releases.

## Summary

- The **two-package split** separates static defaults (`omarchy-settings`) from runtime components (`omarchy`).
- `omarchy-settings` must install before user creation to properly seed `/etc/skel` and system-wide configuration.
- `omarchy` depends on `omarchy-settings` and installs after user accounts exist.
- The source tree organization is documented in [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md) with specific line references defining package boundaries.
- Lifecycle management occurs through `omarchy-provision-user` (initial setup) and `omarchy-reinstall-configs` (maintenance).

## Frequently Asked Questions

### What is the difference between omarchy and omarchy-settings?

The `omarchy-settings` package contains static system defaults, skeleton files for new users, and pre-configuration templates required before account creation. The `omarchy` package contains the runtime desktop environment, user-specific migration scripts, and the Quickshell interface that requires an existing user context to function.

### When should I install omarchy-settings vs omarchy?

Install `omarchy-settings` during system initialization or ISO build—before creating any user accounts. Install `omarchy` only after at least one user account exists, as it depends on the skeleton files and system defaults provided by the settings package.

### How do I upgrade both packages together?

Use the `omarchy-upgrade-to-quattro` command with the appropriate channel flag. Running `omarchy-upgrade-to-quattro --dev` simultaneously updates both `omarchy-dev` and `omarchy-settings-dev`, maintaining the required dependency order and ensuring configuration compatibility.

### What happens if I install omarchy before omarchy-settings?

Installing `omarchy` first violates the package dependency chain defined in the repository. The runtime expects files in `/etc/skel` and system-wide configuration paths (like `/etc/fastfetch/`) to exist. Missing these prerequisites causes provision scripts to fail and prevents proper user environment initialization.