How Omarchy Is Distributed as Arch Linux Packages

Omarchy ships to Arch Linux users as standard pacman packages built from PKGBUILD files maintained in the separate omarchy-pkgs repository, with binary packages served through the Omarchy Package Repository and installable via sudo pacman -S omarchy.

Omarchy, the desktop environment developed by Basecamp, follows Arch Linux packaging conventions to deliver system updates and configuration management. Unlike monolithic distributions that bundle everything into a single image, Omarchy is distributed as modular Arch Linux packages that integrate seamlessly with the native pacman ecosystem. This architecture ensures that every file installed on the system is tracked, versioned, and managed through standard package management tools according to the basecamp/omarchy source code.

The Omarchy Package Repository Architecture

Source Code vs. Packaging Repositories

The main repository (basecamp/omarchy) contains the application source code, while the packaging logic lives in a dedicated sibling repository (omarchy-pkgs). This separation follows Arch best practices by isolating build instructions from application logic.

Each installable component maintains its own PKGBUILD file in the omarchy-pkgs repository. When a new Omarchy release is published, maintainers update the pkgver and source URLs in these PKGBUILDs, then build them into binary packages (.pkg.tar.zst) for distribution through the Omarchy Package Repository.

Package Components and Dependencies

The distribution is split into logical packages to allow granular installation:

• omarchy: Core desktop environment binaries and libraries
• omarchy-settings: Default configuration templates, fonts, and systemd user units
• omarchy-dev: Development headers and build dependencies

PKGBUILD Structure and Installation Directives

The PKGBUILD files include install directives that copy static assets into specific filesystem locations. According to docs/file-layout.md, these packages deploy systemd user units to /usr/lib/systemd/user/ and default configuration templates to /etc/skel/.config/omarchy/.

The omarchy-settings PKGBUILD specifically ships the update notification mechanism as a systemd user unit. This ensures the omarchy-update-user-notify.service starts automatically for users without requiring manual configuration, as implemented in the basecamp/omarchy repository.

How to Install Omarchy Packages

Standard pacman Installation

Users install Omarchy through the Omarchy Package Repository, a private Arch mirror that hosts the binary packages. After configuring the repository in pacman.conf (documented in manual/30-updates.md), install the core system:

sudo pacman -S omarchy omarchy-settings

AUR-Style Installation via Helper Script

For users who prefer building from source, the AUR helper script (bin/omarchy-pkg-aur-install) provides an AUR-style installation experience. This script locates PKGBUILD files—defaulting to ~/Work/omarchy/omarchy-pkgs/pkgbuilds or the ${OMARCHY_PKGBUILDS_DIR} environment variable—and executes makepkg on your behalf:

# Install from local PKGBUILD sources

omarchy-pkg-aur-install omarchy omarchy-settings

Package Validation and File Ownership Testing

Omarchy enforces strict file ownership validation to ensure every installed path is tracked by pacman. The repository includes two critical test suites that verify packaging integrity.

unowned-system-paths-test.sh

Located at test/shell.d/unowned-system-paths-test.sh, this test flags any file written by scripts that is not owned by a PKGBUILD. It verifies that no configuration or binary exists on the system without being tracked by the package manager.

config-test.sh

The test/shell.d/config-test.sh script validates that every PKGBUILD explicitly declares its source-to-destination mappings (lines 115-178). This prevents packaging errors where files might be omitted from the final package archive.

Run these validations manually to verify system integrity:

# Verify all system paths are owned by packages

./test/shell.d/unowned-system-paths-test.sh

# Validate PKGBUILD coverage and file mappings

./test/shell.d/config-test.sh

Inspect package-owned files using standard pacman queries:

# Verify systemd units are properly packaged

pacman -Ql omarchy | grep '/usr/lib/systemd/user/omarchy-.*\.service'

# Check default configuration templates

pacman -Ql omarchy-settings | grep '/etc/skel/.config/omarchy/'

Summary

• Omarchy is distributed as standard Arch Linux packages through the Omarchy Package Repository, not as a custom disk image or script-based installer.
• Packaging logic is separated from source code, with PKGBUILD files maintained in the dedicated omarchy-pkgs repository while source code lives in basecamp/omarchy.
• Installation uses native pacman commands, with an optional AUR helper script (bin/omarchy-pkg-aur-install) for source builds.
• The omarchy-settings package delivers systemd user units and default configs to /usr/lib/ and /etc/skel/ respectively.
• Strict validation via test/shell.d/unowned-system-paths-test.sh and test/shell.d/config-test.sh ensures every file is tracked and no orphaned paths exist on the system.

Frequently Asked Questions

Where are the PKGBUILD files for Omarchy located?

The PKGBUILD files are stored in a separate repository called omarchy-pkgs, not in the main basecamp/omarchy repository. Each package has its own directory with a PKGBUILD file that defines versioning, dependencies, and installation scripts. This separation allows the main repository to focus on source code while the packaging repository handles Arch-specific build instructions.

How do I install Omarchy from the AUR?

While Omarchy primarily distributes through its own package repository, you can use the bin/omarchy-pkg-aur-install helper script to perform AUR-style builds. This script reads PKGBUILD files from ${OMARCHY_PKGBUILDS_DIR} (defaulting to ~/Work/omarchy/omarchy-pkgs/pkgbuilds) and runs makepkg to build and install packages locally. This method is useful for developers or users who want to modify the PKGBUILDs before installation.

What files does the omarchy-settings package install?

According to docs/file-layout.md, the omarchy-settings package installs systemd user units to /usr/lib/systemd/user/ (including omarchy-update-user-notify.service) and default configuration templates to /etc/skel/.config/omarchy/. These files provide the default desktop experience and automatic update notifications for new users created on the system.

How does Omarchy ensure all installed files are tracked by pacman?

Omarchy implements two validation mechanisms in test/shell.d/unowned-system-paths-test.sh and test/shell.d/config-test.sh. The first test verifies that no script writes files to locations not owned by a PKGBUILD, while the second validates that every PKGBUILD properly declares all its installed files. These tests run during CI to prevent orphaned files and ensure complete package management integration.

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