How Omarchy Is Structured as Arch Linux Packages: The Two-Package System Explained

Omarchy is structured as two native Arch Linux packages—omarchy and omarchy-settings—that install the distribution's runtime and system-wide configurations while relying on pacman for dependency resolution and updates.

Omarchy is an Arch Linux-based distribution that extends the base OS with a custom desktop environment built on Hyprland, as documented in docs/manual/01-welcome-to-omarchy.md. Rather than functioning as a monolithic script layer, Omarchy is distributed through the omarchy package repository as discrete units that integrate with standard Arch tooling. According to the omacom/omarchy source code, this architecture allows the distribution to leverage Arch's package management while maintaining strict separation between runtime binaries and system configuration files.

The Dual-Package Architecture

Omarchy's distribution model centers on two distinct packages generated from the repository. This separation ensures that runtime logic remains distinct from system-wide settings that must survive across updates.

The Runtime Package (omarchy)

The primary omarchy package contains the core executables, libraries, and default user configurations required for the distribution to function. As documented in docs/file-layout.md, this package installs:

• The omarchy command-line entry point and all omarchy-* helper utilities located in bin/
• The Quickshell desktop environment definitions
• Default configuration templates that populate user directories on first run

This package represents the active runtime layer that users interact with when executing management commands.

The Settings Package (omarchy-settings)

Complementing the runtime, the omarchy-settings package handles files that must exist at specific system paths. According to docs/file-layout.md, this includes:

• Systemd user services that manage session components
• /etc/ overrides for system-wide defaults
• Files that belong outside of ~/.config but require package manager ownership

The PKGBUILD for this package ensures these paths are properly tracked by pacman, preventing conflicts with user modifications while maintaining system integrity.

Package Build Infrastructure and Testing

While the PKGBUILD definitions reside in a separate omarchy-pkgs repository, the main omacom/omarchy repository contains rigorous tests to verify package integrity. The test suite in test/shell.d/config-test.sh reads PKGBUILD files to confirm that declared files match installation manifests.

Additionally, test/shell.d/unowned-system-paths-test.sh enforces a critical Arch packaging constraint: every file installed to system paths must be owned by a PKGBUILD. This test fails if any runtime component creates files in protected directories without proper package registration, ensuring Omarchy adheres to Arch packaging standards.

The Omarchy Update Pipeline

Omarchy extends standard Arch updates with a safe synchronization process documented in docs/update-process.md. When a user executes omarchy update, the system performs:

1. Keyring synchronization – Updates the Omarchy-specific pacman keyring to ensure package signatures remain valid
2. Mirror synchronization – Runs pacman -Syu against the Omarchy mirror, which tracks Arch's core, extra, and multilib repositories
3. Optional AUR integration – Queries the AUR when optional packages are requested, using yay or paru as backends

This pipeline ensures that Omarchy-specific packages remain in lock-step with the underlying Arch system while maintaining cryptographic verification.

Package Management Helpers

The bin/omarchy CLI provides wrapper commands that standardize package operations while maintaining Omarchy's migration and snapshot logic:

• omarchy pkg add <name> – Resolves the package name against Arch repos or AUR, adds it to the user manifest, and triggers a rebuild
• omarchy pkg drop <name> – Removes the package from the manifest and rebuilds the package set
• omarchy pkg present and omarchy pkg missing – Query commands that inspect the current package state against the declared manifest

These commands wrap pacman (and AUR helpers) to ensure that system state remains synchronized with Omarchy's configuration management layer.

# Install the base Omarchy system after booting Arch

sudo pacman -S omarchy omarchy-settings

# Add an extra Arch package via the Omarchy wrapper

omarchy pkg add vim

# Add an AUR package (calls yay/paru internally)

omarchy pkg add visual-studio-code-bin

# Update the entire system using Omarchy's safe pipeline

omarchy update

Summary

• Omarchy distributes itself as two Arch packages: the omarchy runtime and omarchy-settings for system files.
• PKGBUILDs are maintained in a separate repository but validated through tests in test/shell.d/config-test.sh and test/shell.d/unowned-system-paths-test.sh.
• The omarchy update command synchronizes the keyring before running pacman -Syu, ensuring secure updates against the Omarchy mirror.
• Helper commands like omarchy pkg add wrap pacman and AUR tools while maintaining Omarchy's manifest system.
• All system paths must be owned by a PKGBUILD, as enforced by the unowned system paths test.

Frequently Asked Questions

What are the exact package names for installing Omarchy?

The distribution installs through two package names: omarchy (containing the runtime and CLI tools) and omarchy-settings (containing system-wide configuration files and systemd services). Both must be installed via sudo pacman -S omarchy omarchy-settings to achieve a working system.

Where are the PKGBUILD files located?

The PKGBUILD definitions reside in a separate external repository called omarchy-pkgs, not in the main omacom/omarchy repository. However, the main repository contains test suites in test/shell.d/config-test.sh that reference and validate these external PKGBUILD files against the actual file system layout.

How does Omarchy handle AUR packages?

Omarchy handles AUR packages through wrapper commands that invoke yay or paru under the hood. When you run omarchy pkg add with an AUR package name, the tool resolves the dependency, adds it to the user's manifest, and triggers the AUR helper to build and install the package while maintaining Omarchy's snapshot logic.

Can I use standard pacman commands instead of Omarchy wrappers?

Yes, standard pacman commands function normally on an Omarchy system. However, using omarchy pkg add and omarchy pkg drop is recommended because these commands update Omarchy's internal manifest files that track the system's intended state. Direct pacman usage may cause Omarchy's query commands (omarchy pkg present, omarchy pkg missing) to report inaccurate states, though the underlying Arch packages will still install correctly.

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