# How Omarchy Is Structured: The Two-Package Architecture Explained

> Discover Omarchy's two package architecture. Learn how it separates runtime binaries from system defaults, deploying three layers to populate user home directories for efficient system management.

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

---

**Omarchy uses a two-package mental model that separates runtime binaries from system-wide defaults, deploying three distinct layers to populate user home directories.**

Omarchy is an open-source desktop environment by Basecamp built on Arch Linux. Understanding how Omarchy is structured requires looking at its unique packaging strategy and the three-layer system it uses to manage user configurations from initial install through ongoing updates.

## The Two-Package Mental Model

The architecture cleanly splits functionality between two distinct packages to ensure system defaults exist before the runtime environment is installed.

### The `omarchy` Package

This package contains the **runtime environment**. It ships binaries, themes, and the Quickshell desktop definition:

- **Runtime binaries** live in `bin/` and install to `/usr/bin/omarchy-*` with symlinks under `/usr/share/omarchy/bin/`
- **Installation scripts** in `install/` handle system-wide configuration
- **Migrations** in `migrations/` provide incremental upgrade scripts
- **Desktop shell** components in `shell/` define the Quickshell UI
- **Themes** in `themes/` provide built-in visual defaults

### The `omarchy-settings` Package

This package contains all files that must exist **before** the main `omarchy` package installs:

- **`/etc/skel/`** templates that `useradd -m` copies into new user home directories
- **System-wide drop-ins** under `/etc/` for system configuration
- **Shared data** under `/usr/share` including fonts, Plymouth themes, and SDDM themes
- **Debug utilities** (`omarchy-debug*` binaries) for troubleshooting

Post-install scripts copy these seeds from the package into the target root filesystem, ensuring defaults are present before any user accounts are created.

## Three-Layer User Home Population

Omarchy populates user homes through a deliberate three-phase process documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md).

### 1. Seed

The `omarchy-settings` package ships static defaults to `/etc/skel/`. When administrators create new users with `useradd -m`, Arch Linux copies this entire tree into the user's `$HOME`.

### 2. Finalize

The command `omarchy provision-user` (routed internally as `omarchy finalize user`) runs **once per user** after the seed step. Unlike static seed files, this step performs runtime-specific tasks:

- Expanding `$HOME`-dependent paths that cannot be hardcoded in `/etc/skel/`
- Detecting current hardware state (e.g., GPU mode)
- Installing user-specific themes or plugins

This executes the script located at `bin/omarchy-provision-user` in the repository.

### 3. Resync

Existing users can reset configurations to shipped defaults using `omarchy reinstall-configs`. This command deliberately overwrites `$HOME/.config/omarchy/*` with fresh copies from `/usr/share/omarchy/config/`, allowing users to recover from broken customizations while preserving their data.

## Repository-to-Filesystem Mapping

During the build process, the repository layout maps to specific installation paths:

- `bin/omarchy-*` → `/usr/bin/omarchy-*` (and symlinks in `/usr/share/omarchy/bin/`)
- `install/**` → `/usr/share/omarchy/install/`
- `migrations/**` → `/usr/share/omarchy/migrations/`
- `themes/**` → `/usr/share/omarchy/themes/`
- `shell/**` → `/usr/share/omarchy/shell/`
- `config/**` → `/etc/skel/.config/**` (for new users) and `/usr/share/omarchy/config/**` (resync source)
- `default/**` → System-wide locations including `/etc/skel/.bashrc` and `/etc/fastfetch/config.jsonc`

The file [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) in the repository contains the complete authoritative map of these transformations.

## Environment Bootstrap and Runtime Paths

All entry points source a single bootstrap script: `default/bash/env-bootstrap`. This script:

1. Reads [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) (written by `omarchy-dev-link`) or defaults `OMARCHY_PATH` to `/usr/share/omarchy`
2. Prepends `$OMARCHY_PATH/bin` to `$PATH` **only** when a development link is active
3. Adds Mise tool directories (`$HOME/.local/share/mise/shims` and `$HOME/.local/bin`) for user-installed tools

This bootstrap is referenced from [`/etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main//etc/profile.d/omarchy.sh), user shells, the uwsm session manager, and SSH non-login shells.

## Where Themes and State Live

User-specific data follows XDG conventions to separate ephemeral state from version-controllable configuration:

- **Generated theme state**: `~/.local/state/omarchy/current/`
- **Persistent user configuration**: `~/.config/omarchy/`

This separation allows users to track customizations in Git while still being able to resync core defaults when needed.

## Common Operations

Below are commands that demonstrate working with the Omarchy structure:

```bash

# List all available omarchy commands

omarchy help --list

# Run per-user finalization (typically once after install)

omarchy provision-user

# Reset user config to shipped defaults

omarchy reinstall-configs

# View the environment bootstrap script

cat /usr/share/omarchy/default/bash/env-bootstrap

# Inspect a migration script

cat /usr/share/omarchy/migrations/1782049344.sh

```

## Summary

- **Omarchy** ships runtime binaries and the Quickshell desktop, while **omarchy-settings** provides system-wide defaults and `/etc/skel/` templates.
- User homes populate via three layers: **Seed** (static files from `/etc/skel/`), **Finalize** (runtime `omarchy provision-user`), and **Resync** (`omarchy reinstall-configs`).
- The file `default/bash/env-bootstrap` serves as the single source of truth for `OMARCHY_PATH` and environment setup across all entry points.
- User state lives under `~/.local/state/omarchy/current/` and configuration under `~/.config/omarchy/`, enabling safe resyncs without data loss.

## Frequently Asked Questions

### What is the difference between the `omarchy` and `omarchy-settings` packages?

The `omarchy` package contains the runtime binaries, themes, and Quickshell desktop found in `bin/`, `shell/`, and `themes/`. The `omarchy-settings` package contains files that must exist before Omarchy runs, including `/etc/skel/` templates, system-wide `/etc/` drop-ins, fonts, and the three debug binaries (`omarchy-debug*`). This separation ensures defaults are present before the main software installs.

### When should I run `omarchy provision-user`?

Run `omarchy provision-user` once per user after the initial installation or when creating a new user account. This command handles tasks that cannot be performed by the static seed step, such as expanding `$HOME` paths, detecting current GPU hardware, and installing user-specific plugins or themes that require the live `$OMARCHY_PATH`.

### How do I reset my Omarchy configuration without reinstalling the OS?

Use the `omarchy reinstall-configs` command. This destroys the contents of `~/.config/omarchy/*` and replaces them with the default files shipped in `/usr/share/omarchy/config/`. Your generated theme state in `~/.local/state/omarchy/` remains untouched, allowing you to recover from configuration errors while preserving runtime data.

### Where is `OMARCHY_PATH` defined and how does it affect the system?

`OMARCHY_PATH` is defined in `default/bash/env-bootstrap`, which reads [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) or defaults to `/usr/share/omarchy`. This bootstrap script is sourced by [`/etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main//etc/profile.d/omarchy.sh), user shells, and the uwsm session manager. When active development links exist, the script prepends `$OMARCHY_PATH/bin` to `$PATH`, otherwise it ensures tools installed via Mise are available by adding `$HOME/.local/share/mise/shims` to the path.