# Omarchy File Layout: Complete Guide to Directory Structure and Installation Paths

> Explore the comprehensive Omarchy file layout guide. Understand directory structure and installation paths for Seed, Finalize, and Resync layers. Find official docs in the repository.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-02

---

**The authoritative Omarchy file layout documentation lives in [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md), which maps how source directories transform into system paths across three user-side layers: Seed, Finalize, and Resync.**

The `omacom/omarchy` repository builds two Arch Linux packages—`omarchy` and `omarchy-settings`—that distribute desktop environment components across your filesystem. Understanding this Omarchy file layout is essential for customizing themes, modifying default configurations, or troubleshooting installation issues.

## Locating the Official File Layout Documentation

The definitive reference for Omarchy's on-disk structure is **[`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md)** at the repository root. This document explains the mental model behind the package architecture, detailing exactly how source directories in the git repository map to installation destinations on target systems.

According to the Omarchy source code, the repository is organized into logical segments that correspond to specific filesystem locations after installation. The documentation breaks this down into a build-time map showing transformations like `bin/` becoming `/usr/bin/omarchy-*` and `config/` seeding into `/etc/skel/.config/`.

## Understanding the Three-Layer Configuration Model

Omarchy implements a three-tier system for managing user configurations that balances stable defaults with user customization.

### Seed Layer (Static Defaults)

The **Seed** layer originates from `/etc/skel` on the system. When you create a new user account, files from the repository's `config/` directory populate `/etc/skel/.config/`, establishing baseline settings for Hyprland, Quickshell, and application themes. These defaults remain untouched in system directories, serving as immutable reference points.

### Finalize Layer (Runtime Tweaks)

During first login, the **`omarchy-provision-user`** command executes per-user runtime modifications. This Finalize layer applies hardware-specific adjustments and generates dynamic configuration files that cannot be statically seeded, such as monitor layouts or hardware-specific environment variables.

### Resync Layer (Configuration Reset)

The **Resync** layer provides the **`omarchy-reinstall-configs`** command, which overwrites your current `~/.config/` with the shipped defaults from `/etc/skel`. This mechanism ensures you can return to a known-good state without reinstalling the operating system.

## Build-Time Directory Mappings

The Omarchy file layout transforms source directories into specific system paths during package construction:

| Source Directory | Installation Destination | Purpose |
|-----------------|-------------------------|---------|
| `bin/` | `/usr/bin/omarchy*` | Runtime command entry points |
| `default/` | `/usr/share/omarchy/default/` | System-wide default files and drop-in configurations |
| `config/` | `/etc/skel/.config/` | User configuration seeds for new accounts |
| `etc/` | `/etc/` | System-wide configuration overrides |
| `shell/` | `/usr/share/omarchy/shell/` | Quickshell UI components, desktop bar, and plugins |
| `themes/` | `/usr/share/omarchy/themes/` | Stock theme resources |
| `migrations/` | `/usr/share/omarchy/migrations/` | Per-user evolution scripts applied during updates |
| `install/` | `/usr/share/omarchy/install/` | Root-side setup and hardware detection logic |

## Runtime State and User Configuration Paths

After installation, Omarchy maintains state in specific user directories separate from the read-only system defaults.

Generated runtime state resides in **`~/.local/state/omarchy/current/`**, storing transient data like current theme selections and bar layouts. User-editable configuration modifications belong in **`~/.config/omarchy/`**, while custom themes should be added to **`~/.config/omarchy/themes/`** rather than modifying system paths in `/usr/share/`.

## Practical Navigation Commands

These commands demonstrate how to interact with the Omarchy file layout layers directly:

```bash

# Display the current bar layout (reads from ~/.config/omarchy/shell.json)

omarchy bar get

# Reset all user configurations to shipped defaults (Resync layer)

omarchy-reinstall-configs

# Refresh a single configuration file from the repository defaults

omarchy-refresh-config hypr/hyprland.lua

```

These utilities read from `$HOME/.config/`, fall back to seeded defaults in `/etc/skel`, and can selectively refresh from shipped defaults without affecting unrelated customizations.

## Summary

- The complete Omarchy file layout reference is located in **[`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md)** within the source repository.
- Two Arch packages (`omarchy` and `omarchy-settings`) map source directories like `bin/`, `default/`, and `config/` to system paths during installation.
- Configuration management follows a three-layer model: **Seed** (`/etc/skel` defaults), **Finalize** (`omarchy-provision-user` runtime tweaks), and **Resync** (`omarchy-reinstall-configs` reset capability).
- Runtime state lives in `~/.local/state/omarchy/current/`, while user customizations belong in `~/.config/omarchy/`.
- Use **`omarchy-reinstall-configs`** to restore defaults or **`omarchy-refresh-config`** for granular file restoration.

## Frequently Asked Questions

### Where is the Omarchy file layout officially documented?

The authoritative documentation lives in **[`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md)** at the repository root. This file contains the complete build-time map showing how directories like `bin/`, `default/`, and `config/` transform into system paths such as `/usr/bin/omarchy-*` and `/etc/skel/.config/`.

### What is the difference between /etc/skel and ~/.config/omarchy?

`/etc/skel` stores the **Seed** layer—static default configurations copied to new user accounts during creation. `~/.config/omarchy/` contains your active, user-modified settings. While `/etc/skel` serves as an immutable reference, `~/.config/omarchy/` is where runtime state and custom themes actually live.

### How do I reset my configuration to Omarchy defaults?

Execute **`omarchy-reinstall-configs`** to trigger the Resync layer. This command copies files from `/etc/skel` into your `$HOME` directory, overwriting current configurations with the original shipped defaults. For selective resets, use **`omarchy-refresh-config <path>`** to restore individual files.

### Where are Omarchy binaries installed on the system?

Executable entry points from the repository's `bin/` directory install to **`/usr/bin/`** with the `omarchy-*` prefix. These include `omarchy-provision-user`, `omarchy-reinstall-configs`, and the main `omarchy` command used for querying and modifying runtime state.