How Omarchy Is Structured Into Arch Packages: Core, Optional, and Meta-Packages Explained

Omarchy delivers its desktop environment as a modular collection of Arch Linux packages organized into core base packages, optional extras, and meta-packages, managed through Bash-based provisioning scripts in the install/ directory.

The Omarchy distribution by Basecamp takes a fundamentally Arch-package-centric approach to system construction, treating the entire desktop experience as a curated set of Pacman packages rather than a monolithic image. Understanding how Omarchy is structured into Arch packages reveals why the system remains both minimal and extensible, using plain-text package lists and sophisticated provisioning logic to assemble the final environment.

Core Package Architecture

The foundation of Omarchy rests in install/omarchy-base.packages, a plain-text manifest that defines the minimal Omarchy environment shipped on the ISO. Each line in this file names a specific Pacman package that the ISO builder installs during base system creation, ensuring identical package sets for both online and offline installations.

ISO Builder Integration

The core package list serves dual purposes: it defines the initial installation set and generates the offline mirror. According to the basecamp/omarchy source code, the ISO builder uses this file to synchronize packages into a local cache, enabling fully offline installs with the exact same package versions found in online builds.

Base System Provisioning

Beyond package installation, the install/provisioning/ directory contains systemd services and scripts that activate these packages into a working desktop. Files like install/provisioning/omarchy-system-factory-reset-finish.service run during first boot to configure systemd services, user units, and essential configuration files.

Optional Packages and Meta-Package Groups

Omarchy extends its functionality through install/omarchy-other.packages, which lists optional Pacman packages not included in the base ISO. These packages remain available for installation after initial setup, allowing users to add fonts, drivers, and applications without bloating the core image.

Meta-Package Organization

Rather than installing individual packages, users typically consume meta-packages—small wrapper packages that pull in groups of related software. Examples include omarchy-gaming for game launchers and drivers, and omarchy-development for programming tools. These meta-packages appear as entries in the various install/*.packages files scattered throughout the repository.

Post-Installation and Migration Infrastructure

The install/post-install/ directory handles system-specific configuration after the base packages land. The script install/post-install/pacman.sh manages Pacman keyring updates and package database refreshes, while other scripts handle Snapper configuration and hardware-specific tweaks.

Release Migration System

When upgrading between Omarchy versions (such as migrating from Omarchy 3 to Omarchy 4), the system relies on agents/skills/migrations.md and the bin/omarchy-migrate utility. These migration scripts contain version-specific logic for adjusting configurations, updating service files, and handling breaking changes between releases.

Practical Package Management Examples

Working with Omarchy's package structure requires understanding its CLI utilities and file locations.

To inspect the core package set:

# Display the core package list shipped with the ISO

cat "$(omarchy-path)/install/omarchy-base.packages"

To add optional functionality via meta-packages:

# Install the gaming meta-package with related drivers and launchers

omarchy-pkg-add omarchy-gaming

To execute migration steps manually:

# Run a specific migration (e.g., ZRAM configuration fixes)

omarchy-migrate zram

ISO builders can generate offline mirrors using the core package list:

# Synchronize core packages to an offline mirror directory

rsync -av --files-from=$(omarchy-path)/install/omarchy-base.packages \
      /var/cache/pacman/pkg/ /path/to/offline/mirror/

Summary

• Omarchy uses a three-tier package architecture: core base packages (install/omarchy-base.packages), optional extras (install/omarchy-other.packages), and convenience meta-packages.
• The ISO builder consumes plain-text package lists to create both the installation media and offline mirrors, ensuring reproducible package sets.
• Provisioning scripts in install/provisioning/ and install/post-install/ transform installed packages into a configured desktop environment.
• The migration framework (bin/omarchy-migrate and agents/skills/migrations.md) handles upgrades between Omarchy releases by applying version-specific fixes.
• Users interact with the package system through utilities like omarchy-pkg-add and omarchy-migrate, which abstract Pacman and AUR operations.

Frequently Asked Questions

What is the difference between omarchy-base.packages and omarchy-other.packages?

The omarchy-base.packages file contains the minimal set of Pacman packages installed on every Omarchy ISO, forming the core desktop environment. The omarchy-other.packages file lists optional packages that users can install after initial setup, such as additional fonts, development tools, or gaming software, keeping the base image lean while offering extensibility.

How do meta-packages work in Omarchy?

Meta-packages in Omarchy are small wrapper packages (like omarchy-gaming or omarchy-development) that declare dependencies on groups of related software. When you install a meta-package via omarchy-pkg-add, Pacman automatically resolves and installs all associated packages, simplifying the process of adding complex functionality without tracking individual dependencies manually.

Where does Omarchy store its installation and provisioning logic?

All installation, provisioning, and post-installation logic resides in the install/ directory of the repository. The install/provisioning/ subdirectory contains systemd services and first-boot configuration scripts, while install/post-install/ handles ongoing maintenance tasks like Pacman keyring updates and hardware-specific adjustments.

How does Omarchy handle upgrades between major versions?

Omarchy manages version upgrades through a migration system documented in agents/skills/migrations.md and executed via the bin/omarchy-migrate script. This framework applies targeted fixes—such as configuration updates or service migrations—when moving between releases (e.g., Omarchy 3 to Omarchy 4), ensuring system continuity without requiring full reinstallation.

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