# How Omarchy Is Structured Into Arch Packages: Core, Optional, and Meta-Packages Explained > Understand Omarchy's Arch package structure: core, optional, and meta-packages. Learn how this modular desktop environment is organized and provisioned. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: architecture - Published: 2026-08-27 --- **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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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: ```bash # Display the core package list shipped with the ISO cat "$(omarchy-path)/install/omarchy-base.packages" ``` To add optional functionality via meta-packages: ```bash # Install the gaming meta-package with related drivers and launchers omarchy-pkg-add omarchy-gaming ``` To execute migration steps manually: ```bash # Run a specific migration (e.g., ZRAM configuration fixes) omarchy-migrate zram ``` ISO builders can generate offline mirrors using the core package list: ```bash # 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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.