Understanding the Difference Between Omarchy and Omarchy-Settings Packages

The omarchy-settings package provides the static baseline configuration required before the runtime starts, while the omarchy package contains the executable runtime, CLI tools, and Quickshell desktop.

Omarchy is Basecamp's open-source Arch Linux development environment configuration. Understanding the difference between omarchy and omarchy-settings packages is essential for system administration and troubleshooting, as the codebase is deliberately split into two distinct Arch packages that enforce a strict separation between static configuration and executable runtime code.

Architectural Separation: Code vs. Configuration

As documented in docs/file-layout.md, the repository enforces a deliberate architectural boundary that mirrors the classic separation between configuration and code.

omarchy-settings (Static Configuration Layer)

The omarchy-settings package serves as the foundation that must be pre-installed before the runtime can initialize. According to the file layout documentation, this package ships:

• Static defaults for the user's home directory under /etc/skel
• Default systemd user units located in /usr/lib/systemd/user/
• Configuration templates, fonts, and icons
• Auxiliary scripts required for baseline environment setup

The documentation explicitly states that omarchy-settings is installed when you run omarchy-install and provides the baseline configuration that the Omarchy runtime expects.

omarchy (Runtime and CLI Layer)

The omarchy package contains the active runtime components. It provides:

• The Omarchy command-line interface (CLI)
• The Quickshell QML desktop environment (shell/)
• Theme handling and management utilities
• Helper utilities and agent scripts located in bin/ and agents/

The runtime depends on omarchy-settings but does not bundle the static configuration files. This design ensures that user customizations in ~/.config and ~/.local remain isolated from runtime updates.

Installation Sequence and Dependencies

The installation process respects the dependency hierarchy between these packages. As outlined in docs/file-layout.md, the flow follows a strict order:

1. omarchy-install pulls the omarchy-settings package first to seed the required system files and skeleton directories.
2. Once baseline files are in place, the omarchy package is installed to provide the executable runtime.
3. The runtime can then start, reading its configuration from the files previously seeded by omarchy-settings.

Independent Update Mechanisms

The docs/update-process.md file explains how updates are handled separately for each package, ensuring that configuration changes and code changes do not interfere with each other.

When a new version is released:

• If only omarchy has a newer version, the runtime upgrades without touching static defaults, preventing unintentional overwriting of user customizations.
• If omarchy-settings has a newer version, the update process replaces seeded configuration files (e.g., /etc/skel/.config/…, systemd user units) before or alongside the runtime upgrade.

This separation allows configuration defaults to evolve without requiring a full runtime reinstall. The update checker implemented in bin/omarchy-update-available examines both package versions to determine which components require upgrading.

Channel Management and Package Pairs

Both packages are managed as synchronized pairs across distribution channels. The bin/omarchy-channel-set script switches between stable and development channels by manipulating both packages simultaneously to maintain version consistency.

# Switch to the development channel (installs both dev packages)

omarchy-channel-set dev

# Verify which channel is currently active

omarchy-channel-current

The system tracks the active channel by checking for the presence of either package pair (omarchy/omarchy-settings for stable, or omarchy-dev/omarchy-settings-dev for development) via the bin/omarchy-channel-current utility.

Summary

• omarchy-settings provides static baseline configuration, systemd units, and skeleton files that must exist in /etc/skel and system directories before the runtime initializes.
• omarchy delivers the executable runtime, CLI tools, Quickshell desktop, and theme management utilities located in bin/ and shell/.
• The installation process always installs omarchy-settings before omarchy to satisfy the runtime's dependency on pre-installed configuration templates.
• Updates are handled independently; runtime updates do not overwrite user configurations in ~/.config, while settings updates refresh system-wide defaults.
• Channel switching operates on both packages as a pair, ensuring that development or stable versions remain synchronized.

Frequently Asked Questions

Can I install omarchy without omarchy-settings?

No. The omarchy package explicitly depends on omarchy-settings being installed first. The runtime expects the static configuration files, systemd units, and skeleton directory structures to exist in /etc/skel and /usr/lib/systemd/user/ before it starts. Attempting to run the runtime without the settings package would result in missing configuration templates and failed service initialization.

Will updating omarchy overwrite my personal configuration files?

No. Because the runtime and static defaults are packaged separately, updating omarchy only upgrades the CLI tools and Quickshell desktop without touching files in your home directory. The omarchy-settings package manages system-wide defaults under /etc/skel and system directories, leaving your ~/.config customizations intact unless you explicitly choose to refresh the settings package independently.

How do I switch between stable and development channels?

Use the omarchy-channel-set command followed by the desired channel name. Running omarchy-channel-set dev installs the development versions of both packages (omarchy-dev and omarchy-settings-dev), while omarchy-channel-set stable reverts to the standard releases. The omarchy-channel-current utility inspects which package pair is installed to report the active channel.

What happens if omarchy-settings is updated but omarchy is not?

When omarchy-settings receives an update without a corresponding omarchy update, the system refreshes the seeded configuration files, systemd units, and skeleton templates to their latest defaults. This allows the distribution to evolve baseline configurations and add new system services without requiring a full runtime upgrade, while the existing runtime continues to function with the updated defaults.

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