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

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, 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)
• 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) 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.

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

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

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