# Omarchy File Layout: Understanding the Repository Structure and System Integration

> Explore the Omarchy file layout for the basecamp/omarchy repository. Understand how Arch packages map directories to system paths for seamless integration across user lifecycles.

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

---

**Omarchy organizes its source code around two core Arch packages—`omarchy` and `omarchy-settings`—that map repository directories to system paths like `/usr/share/omarchy/`, `/etc/skel/`, and `/usr/bin/` across three distinct user lifecycle phases.**

Omarchy is a desktop environment distribution built for Arch Linux that uses a distinctive file organization strategy. Understanding the Omarchy file layout is essential for contributors packaging customizations or users troubleshooting their installations. The repository structure directly dictates how files land on a live system through two primary packages and the `omarchy-provision-user` lifecycle.

## Three-Phase User Lifecycle

The Omarchy file layout supports three distinct phases in a user’s lifecycle, each interacting with different parts of the filesystem.

### Seed Phase

During the **seed phase**, static defaults propagate to new user accounts via `/etc/skel`. The `config/**` directory contents are installed to `/etc/skel/.config/**`, ensuring that `useradd -m` copies Omarchy’s default configurations—such as window manager settings and application preferences—into every newly created home directory.

### Finalize Phase

The **finalize phase** executes once per user via `omarchy-provision-user`, which runs scripts from `install/user/**` (coordinated through [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh)). This phase handles actions requiring `$HOME` expansion, live `$OMARCHY_PATH` detection, or hardware-specific configurations that cannot be statically seeded.

### Resync Phase

When users execute `omarchy-reinstall-configs`, the **resync phase** clobbers existing configurations back to shipped defaults. This process sources files from `config/**` and utilizes helpers in `install/provisioning/**` to restore the system to its baseline state without requiring a full reinstall.

## Repository to System Path Mapping

Files in the Omarchy repository build into two Arch packages with distinct installation targets. The following table illustrates how source paths translate to runtime locations:

| Repository Path | Package | Installed Location |
|-----------------|---------|-------------------|
| `bin/omarchy-*` | **omarchy** | `/usr/bin/omarchy-*` (with symlinks in `/usr/share/omarchy/bin/`) |
| `bin/omarchy‑debug*` | **omarchy-settings** | `/usr/bin/` (prerequisite utilities) |
| `config/**` | **omarchy-settings** | `/etc/skel/.config/**` (seed) and `/usr/share/omarchy/config/**` (resync source) |
| `default/**` | **omarchy-settings** | `/usr/share/omarchy/default/` (systemd units, fonts, bash bootstrap) |
| `etc/**` | **omarchy-settings** | `/etc/**` (via post-install scriptlet) |
| `install/**` | **omarchy** | `/usr/share/omarchy/install/` |
| `migrations/**` | **omarchy** | `/usr/share/omarchy/migrations/` |
| `themes/**` | **omarchy** | `/usr/share/omarchy/themes/` |
| `shell/**` | **omarchy** | `/usr/share/omarchy/shell/` |
| `applications/*.desktop` | **omarchy-settings** | `/etc/skel/.local/share/applications/` and `/usr/share/icons/hicolor/` |

## Core Directory Structure

Understanding the purpose of each top-level directory clarifies the Omarchy file layout for developers and system administrators.

### `bin/` Directory

The `bin/` directory contains executable scripts that become system commands. Files matching `bin/omarchy-*` install to `/usr/bin/` and provide the primary CLI interface, including `omarchy-provision-user`, `omarchy-reinstall-configs`, and `omarchy-migrate`. Debug utilities prefixed with `omarchy-debug` ship in the base `omarchy-settings` package to ensure availability before the main package installs.

### `config/` Directory

Configuration templates reside in `config/**`, serving dual purposes: seeding new user accounts via `/etc/skel/.config/` and providing the source of truth for resync operations at `/usr/share/omarchy/config/`. These files define the default desktop environment behavior for window managers, terminal emulators, and application launchers.

### `install/` Directory

The `install/` hierarchy contains scripts executed during system installation and user provisioning. The path [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh) orchestrates per-user finalization, while `install/provisioning/**` stores helpers for deferred first-boot configuration. System-wide installation logic triggered by `omarchy-apply-system` during ISO generation also resides here.

### `migrations/` Directory

Per-user migration scripts live in `migrations/` and are applied by `omarchy-migrate`. These scripts handle configuration updates between Omarchy versions, with completion markers stored under `~/.local/state/omarchy/migrations/` to prevent duplicate execution.

### `themes/` and `shell/` Directories

Visual customization files are organized into `themes/` (built-in theme packages) and `shell/` (Quickshell desktop configuration and QML files). Both directories install to `/usr/share/omarchy/`, providing the runtime assets required by the compositor and desktop shell.

### `default/` Directory

System-wide defaults that apply regardless of user configuration reside in `default/`. This includes `default/bash/env-bootstrap`, which establishes the `OMARCHY_PATH` environment variable and adjusts `PATH` for both regular shells and sudo contexts. This script is sourced by [`/etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main//etc/profile.d/omarchy.sh), `/etc/skel/.bashrc`, and various uwsm session files.

### `etc/` and `etc-overrides/` Directories

Files that must override upstream package configurations (such as [`/etc/nsswitch.conf`](https://github.com/basecamp/omarchy/blob/main//etc/nsswitch.conf)) are staged in `etc/` and copied into place by post-install scriptlets. This approach ensures Omarchy-specific system settings take precedence without conflicting with Arch Linux base package updates.

## Practical Commands for Exploring the Layout

Use these commands to inspect the Omarchy file layout on your system:

```bash

# Display the repository's top-level structure

tree -L 2 .

# List all installed Omarchy binaries

ls /usr/bin/omarchy-*

# View the current migration status

omarchy-migrate --pending

# Resync home configuration to shipped defaults

omarchy-reinstall-configs

```

## Summary

- **Two-package architecture**: The `omarchy` package contains binaries and install scripts, while `omarchy-settings` handles configurations and system defaults.
- **Three-phase deployment**: Files flow through **seed** (`/etc/skel`), **finalize** (`install/user/`), and **resync** (`omarchy-reinstall-configs`) phases to manage user configuration lifecycles.
- **Path mapping**: Repository directories like `config/`, `themes/`, and `shell/` map to `/usr/share/omarchy/` or `/etc/skel/` depending on their intended scope.
- **Environment bootstrap**: The `default/bash/env-bootstrap` script establishes critical paths via `/etc/profile.d/` integration.
- **Migration system**: Version updates are handled through `migrations/` scripts executed by `omarchy-migrate` with state tracked in `~/.local/state/omarchy/`.

## Frequently Asked Questions

### Where are Omarchy's default user configurations stored?

Default user configurations reside in the `config/` directory of the repository, which installs to `/etc/skel/.config/**` for seeding new users and `/usr/share/omarchy/config/**` for resync operations. When you run `omarchy-reinstall-configs`, the system copies files from the latter location to restore defaults.

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

The `omarchy` package contains runtime binaries (`bin/omarchy-*`), installation scripts (`install/`), themes, and the shell configuration. The `omarchy-settings` package handles system-wide defaults (`default/`), skeleton configurations (`config/`), override files (`etc/`), and prerequisite debug utilities required before the main package installation completes.

### How does Omarchy handle user provisioning on first login?

Omarchy uses `omarchy-provision-user` during the finalize phase to execute scripts from `install/user/` that require `$HOME` expansion or hardware detection. Additionally, `omarchy-provision-first-run` triggers after the first graphical login to wire up user services, apply GNOME/GTK settings, and perform speaker tuning.

### Where should I look to understand the authoritative repository structure?

The [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) file in the repository root provides the authoritative description of the Omarchy file layout and installation mapping. This document details how each directory translates to system paths and explains the architectural decisions behind the three-phase user lifecycle.