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

The authoritative Omarchy file layout documentation lives in 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 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:

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

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