Omarchy File Layout: Understanding the Repository Structure and System Integration

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). 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 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, /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) 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:

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

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