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

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

# Configure the stable channel

omarchy channel set stable

# Install both runtime and defaults

sudo pacman -S --needed omarchy omarchy-settings

Installing the Development Stack

# 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:

omarchy reinstall-configs

Verifying Your Current Installation

Check which package pair is active on your system:

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

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