How Omarchy Is Distributed and Packaged: Arch Linux Package Management Explained

Omarchy is distributed exclusively as standard Arch Linux packages managed through pacman, with a curated mirror, channel-based updates, and optional AUR support for third-party software.

The Omarchy project takes a unique approach to Linux distribution: rather than building a custom ISO or container images, it layers a curated system configuration on top of Arch Linux through native package management. This article examines the packaging architecture, update mechanisms, and distribution channels based on the source code in omacom/omarchy.

The Core Package Architecture

Omarchy's distribution model centers on three primary packages built from the omarchy-pkgs repository. According to docs/file-layout.md, two Arch packages are built directly from the main Omarchy repository:

Package	Purpose
omarchy	The main system containing commands, default configurations, and systemd units
omarchy-dev	Development-channel variant tracking the latest git checkout
omarchy-settings	User-editable defaults including systemd services and config files

These packages are published to the Omarchy Arch Mirror, which the installer automatically adds to your system's Pacman configuration. This integration means standard Arch commands work seamlessly alongside Omarchy-specific wrappers.

The Update Pipeline: From Mirror to Migration

The bin/omarchy-update script orchestrates the entire update process. As documented in docs/update-process.md, the pipeline follows four distinct phases:

1. Version detection — Queries pacman -Q omarchy via bin/omarchy-version to establish the current state
2. Package list synchronization — Pulls the latest metadata from the Omarchy mirror
3. Package installation — Installs updated Omarchy packages, including channel switches when requested
4. Migration execution — Runs automated migrations shipped with the updated packages

This design ensures that system state remains reproducible: each update is a discrete package transaction that can be rolled back through Pacman if necessary.

Channel-Based Distribution

Omarchy supports version channels for different stability requirements. The omarchy version-channel command switches between tracks:

# Switch to the development edge channel

omarchy version-channel edge
omarchy update

The edge channel installs omarchy-dev packages built from the latest git checkout, while the default channel follows tested releases.

Package Management Commands

Omarchy provides wrapper commands that add safety checks to standard Pacman operations. The bin/omarchy-pkg-add and corresponding bin/omarchy-pkg-drop scripts handle granular package changes:

# Install an additional Arch package with Omarchy verification

omarchy pkg add neovim

# Remove an unneeded package

omarchy pkg drop neovim

These wrappers ensure that package operations respect Omarchy's configuration boundaries and system integrity checks.

AUR Integration for Optional Software

For third-party software not in official repositories, Omarchy integrates with the Arch User Repository (AUR). The omarchy update-aur-pkgs command wraps yay -Sua to update foreign packages when detected.

This approach keeps the core Omarchy packages minimal and curated while allowing unlimited extensibility through the AUR ecosystem:

# Update all installed AUR packages

omarchy update-aur-pkgs

Key Source Files and Their Roles

File Path	Responsibility
bin/omarchy-update	Main entry point for the full update pipeline
bin/omarchy-version	Reports installed package version via pacman -Q
bin/omarchy-pkg-add	Safeguarded wrapper around pacman -S
docs/update-process.md	Technical documentation of the package flow
docs/file-layout.md	Package composition and build definitions
manual/30-updates.md	User-facing update workflow guide

Summary

• Omarchy is distributed as native Arch packages, not containers or custom images
• Three package variants—omarchy, omarchy-dev, and omarchy-settings—cover production, development, and configuration needs
• The Omarchy Arch Mirror integrates with pacman for seamless updates
• omarchy update runs a four-phase pipeline: version check, sync, install, and migrate
• Channel switching enables rapid testing of development builds
• AUR support through omarchy update-aur-pkgs extends the package ecosystem

Frequently Asked Questions

How do I check my current Omarchy version?

Run omarchy version or bin/omarchy-version, which executes pacman -Q omarchy to query the installed package version. This returns the exact package release from the Omarchy mirror.

Can I use standard Pacman commands instead of Omarchy wrappers?

Yes. The Omarchy mirror is a standard Pacman repository, so pacman -Syu works directly. However, omarchy update adds migration steps and channel handling that raw Pacman commands skip.

What happens when I switch to the edge channel?

The omarchy version-channel edge command reconfigures your system to track omarchy-dev packages. The next omarchy update replaces stable packages with builds from the latest git commit, enabling early access to features at potential stability cost.

Does Omarchy support offline installation?

No. As a rolling-release Arch-based distribution, Omarchy requires network access to the Omarchy Arch Mirror during installation and updates. All packages are retrieved dynamically rather than bundled in an offline-capable image.

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