How Omarchy Maps Repository Sources to Installed Packages: A Deep Dive Into Its Package Mapping System

Omarchy uses a data-driven associative array omarchy_pkgbuild to map source IDs discovered in the install/ directory tree to Pacman package names, enabling modular, manifest-based system installation.

The basecamp/omarchy repository implements a clean separation between configuration sources and system packages. Rather than embedding package names directly in source scripts, Omarchy delegates the mapping to a centralized lookup table. This design lets developers add new system features by defining a source manifest and a single entry in a hardware-specific mapping file.

How Source Discovery Works

Before any package can be installed, Omarchy must identify which sources are available. The framework treats every subdirectory under install/ as a potential source of system configuration, UI components, or hardware support.

The discovery process begins in install/helpers/logging.sh. This helper walks the install/ hierarchy and extracts source IDs—unique identifiers that represent discrete installable units. Each source file explicitly declares its ID through a variable assignment:

# Example: install/user/tmux-config.sh

source_id="tmux-config"

Sources can also be defined in YAML-style manifest files that use an id: key. The logging helper normalizes these declarations into a flat list that downstream scripts consume.

The Source-to-Package Mapping Mechanism

The core mapping logic resides in install/post-install/pacman.sh. This script sources hardware-specific Pacman configurations and builds an associative array that bridges source IDs to their corresponding PKGBUILD names.

The omarchy_pkgbuild Associative Array

Hardware-specific mappings live in install/hardware/pacman.sh. This file exports omarchy_pkgbuild as a Bash associative array where:

• Keys = source IDs (e.g., "tmux-config", "nvidia-gpu")
• Values = package names installable via Pacman (e.g., "omarchy-tmux-config")

# install/hardware/pacman.sh

declare -A omarchy_pkgbuild=(
    ["base-shell"]="omarchy-base-shell"
    ["tmux-config"]="omarchy-tmux-config"
    ["nvidia-gpu"]="omarchy-nvidia"
    ["wayland-desktop"]="omarchy-wayland"
    # Additional mappings...

)

The post-install script iterates over available sources and resolves each to its package:

# install/post-install/pacman.sh

source "$OMARCHY_INSTALL/hardware/pacman.sh"

for src in "${selected_sources[@]}"; do
    if [[ -n "${omarchy_pkgbuild[$src]}" ]]; then
        pkg="${omarchy_pkgbuild[$src]}"
        # Delegated to package manager helper

        omarchy-pkg-add "$pkg"
    else
        log_warn "No package mapping for source: $src"
    fi
done

Package Installation via CLI Helpers

The mapping table enables simple, source-oriented CLI commands. Users interact with source IDs, not package names—the resolution happens automatically.

Adding a Source

$ omarchy pkg-add tmux-config

Behind the scenes in bin/omarchy-pkg-add:

#!/usr/bin/env bash

# bin/omarchy-pkg-add

source "$OMARCHY_INSTALL/hardware/pacman.sh"

source_id="$1"
pkg="${omarchy_pkgbuild[$source_id]}"

if [[ -z "$pkg" ]]; then
    echo "Error: Unknown source '$source_id'" >&2
    exit 1
fi

sudo pacman -S --needed "$pkg"

Removing a Source

$ omarchy pkg-drop nvidia-gpu

The bin/omarchy-pkg-drop helper performs the inverse lookup and uninstalls the mapped package.

Architecture Benefits of This Mapping Design

This indirection layer provides several operational advantages:

• Hardware abstraction – Different hardware/pacman.sh variants can map the same source ID to platform-specific packages
• Source portability – Source scripts remain package-manager-agnostic
• Atomic updates – Changing a mapping updates all dependent installations
• Auditability – The complete source-to-package relationship is visible in one file

Complete Workflow Example

Consider adding GPU support to an Omarchy installation:

1. Create the source (configuration scripts)

# install/hardware/nvidia-gpu.sh

source_id="nvidia-gpu"

configure_nvidia() {
    # X11/Wayland configuration, environment variables, etc.

}

2. Register the mapping

# install/hardware/pacman.sh

omarchy_pkgbuild["nvidia-gpu"]="omarchy-nvidia-driver"

3. Enable via CLI

$ omarchy pkg-add nvidia-gpu

# Resolves to: pacman -S omarchy-nvidia-driver

Key Implementation Files

File	Purpose	GitHub Link
install/helpers/logging.sh	Source discovery and ID extraction	View source
install/post-install/pacman.sh	Orchestrates mapping and installation	View source
install/hardware/pacman.sh	Defines omarchy_pkgbuild associative array	View source
bin/omarchy-pkg-add	CLI resolver for installing mapped packages	View source
bin/omarchy-pkg-drop	CLI resolver for removing mapped packages	View source
docs/file-layout.md	Repository structure documentation	View source

Summary

• Omarchy's source discovery scans the install/ tree for source_id declarations
• The omarchy_pkgbuild associative array in install/hardware/pacman.sh maps source IDs to Pacman package names
• install/post-install/pacman.sh orchestrates batch installation by iterating over selected sources and resolving each through the mapping table
• CLI helpers omarchy-pkg-add and omarchy-pkg-drop provide user-friendly, source-oriented package management
• This data-driven architecture decouples source definitions from package names, enabling hardware-specific variants and simplified maintenance

Frequently Asked Questions

What happens if a source ID has no entry in omarchy_pkgbuild?

The installation script logs a warning and skips that source. In install/post-install/pacman.sh, the conditional [[ -n "${omarchy_pkgbuild[$src]}" ]] guards against null lookups, preventing Pacman errors while surfacing configuration gaps.

Can different hardware targets use different packages for the same source?

Yes. The hardware/pacman.sh file is sourced dynamically based on detected hardware or explicit target selection. AMD systems might map "gpu-drivers" to omarchy-amdgpu while NVIDIA systems map it to omarchy-nvidia, using identical source configurations but different packages.

How do I add a custom source that doesn't need a package?

Omit the entry from omarchy_pkgbuild. The source script in install/ still executes during post-installation, but no Pacman transaction occurs. This supports pure configuration sources like dotfile deployments or service enablement that don't require new system packages.

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