Difference Between omarchy and omarchy-settings Packages

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

# From bin/omarchy-upgrade-to-quattro

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

# 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 (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 (lines 84-89). Mismatched pairs are rejected to prevent runtime–configuration version skew.

# 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 (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 (lines 125-137)	Ensures settings updates trigger notifications
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.

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