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

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

# Set channel to stable (default)

omarchy channel set stable

# Install both required packages

sudo pacman -S --needed omarchy omarchy-settings

Install Development (Edge) Omarchy

# Switch to edge channel

omarchy channel set dev

# Install development pair

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

Verify Current Installation

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:

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	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	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 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.

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