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

> Discover how Omarchy maps repository sources to installed packages using its data-driven associative array for modular, manifest-based system installation.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-20

---

**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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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"`)

```bash

# 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:

```bash

# 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

```bash
$ omarchy pkg-add tmux-config

```

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

```bash
#!/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

```bash
$ 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`](https://github.com/basecamp/omarchy/blob/main/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)

```bash

# install/hardware/nvidia-gpu.sh

source_id="nvidia-gpu"

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

}

```

2. **Register the mapping**

```bash

# install/hardware/pacman.sh

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

```

3. **Enable via CLI**

```bash
$ omarchy pkg-add nvidia-gpu

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

```

## Key Implementation Files

| File | Purpose | GitHub Link |
|------|---------|-------------|
| [`install/helpers/logging.sh`](https://github.com/basecamp/omarchy/blob/main/install/helpers/logging.sh) | Source discovery and ID extraction | [View source](https://github.com/basecamp/omarchy/blob/quattro/install/helpers/logging.sh) |
| [`install/post-install/pacman.sh`](https://github.com/basecamp/omarchy/blob/main/install/post-install/pacman.sh) | Orchestrates mapping and installation | [View source](https://github.com/basecamp/omarchy/blob/quattro/install/post-install/pacman.sh) |
| [`install/hardware/pacman.sh`](https://github.com/basecamp/omarchy/blob/main/install/hardware/pacman.sh) | Defines `omarchy_pkgbuild` associative array | [View source](https://github.com/basecamp/omarchy/blob/quattro/install/hardware/pacman.sh) |
| `bin/omarchy-pkg-add` | CLI resolver for installing mapped packages | [View source](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-pkg-add) |
| `bin/omarchy-pkg-drop` | CLI resolver for removing mapped packages | [View source](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-pkg-drop) |
| [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) | Repository structure documentation | [View source](https://github.com/basecamp/omarchy/blob/quattro/docs/file-layout.md) |

## Summary

- Omarchy's **source discovery** scans the `install/` tree for `source_id` declarations
- The **`omarchy_pkgbuild`** associative array in [`install/hardware/pacman.sh`](https://github.com/basecamp/omarchy/blob/main/install/hardware/pacman.sh) maps source IDs to Pacman package names
- **[`install/post-install/pacman.sh`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.