How Omarchy's File Layout Maps to Installed Paths on Arch Linux

Omarchy splits its repository into two logical packages—omarchy (runtime) and omarchy-settings (pre-install configuration)—with each subtree mapped to specific system paths via build-time transformations.

The Omarchy desktop distribution for Arch Linux uses a carefully structured repository layout that deterministically translates into installed file locations. Understanding this mapping helps administrators customize installations, debug configuration issues, and predict where files land after package installation. The authoritative reference lives in docs/file-layout.md as implemented in basecamp/omarchy.

The Two-Package Architecture

Omarchy's build system produces two distinct packages from a single repository. This separation allows minimal systems to bootstrap with omarchy-settings before the full runtime is available.

Package	Purpose	Repository Sources
omarchy	Runtime binaries, themes, and system tools	bin/omarchy-*, themes/, shell/, install/, migrations/
omarchy-settings	Pre-install configuration, skeleton files, and system drop-ins	config/, etc/, default/, applications/, bin/omarchy-debug*

Files from the omarchy-settings package install first, providing the foundation that omarchy finalize user later activates when creating new user accounts.

Runtime Binary Mapping: bin/ to /usr/bin/

Compiled executables and shell scripts in bin/omarchy-* become system commands.

# Repository path → installed location

bin/omarchy              → /usr/bin/omarchy
bin/omarchy-*            → /usr/bin/omarchy-*
bin/omarchy-debug*       → /usr/bin/omarchy-debug*  (settings package)

A secondary copy exists at /usr/share/omarchy/bin/ for internal reference. The debug variants ship in omarchy-settings specifically to enable troubleshooting before the main package installation completes.

Check your installation:

$ which omarchy
/usr/bin/omarchy

$ ls /usr/share/omarchy/bin/
omarchy  omarchy-apply-system  omarchy-refresh-config  ...

System Resource Directories

Immutable data files install under /usr/share/omarchy/, creating a predictable namespace for Omarchy's assets.

Repository Path	Installed Location	Contents
install/**	/usr/share/omarchy/install/	System installation helpers consumed by omarchy-apply-system
migrations/**	/usr/share/omarchy/migrations/	Per-user migration scripts run during upgrades
themes/**	/usr/share/omarchy/themes/	Stock themes (white, vantablack, etc.)
shell/**	/usr/share/omarchy/shell/	Shell integration scripts
version	/usr/share/omarchy/version	Version marker (also copied to /etc/skel/.local/state/omarchy/migrations/ for new users)

List available themes post-installation:

ls /usr/share/omarchy/themes/

# → white  vantablack  [other bundled themes]

Package Hooks and System Integration

Arch Linux package manager integration files land in standard ALPM locations:

# Repository: default/libalpm/hooks/*.hook

# Installed:  /usr/share/libalpm/hooks/*.hook

cat /usr/share/libalpm/hooks/omarchy-upgrade.hook

# → triggers maintenance during system upgrades

These hooks execute automatically when pacman installs or upgrades Omarchy packages.

User Configuration Seeding: /etc/skel/ Pattern

The config/ directory and select applications/ files populate new user home directories via the skeleton directory mechanism.

Source	Seeds To	Purpose
config/**	/etc/skel/.config/** → ~/.config/**	Dotfile defaults (Hyprland, Waybar, etc.)
applications/*.desktop	/etc/skel/.local/share/applications/	Default application launchers
logo.*, icon.*	/etc/skel/.config/omarchy/branding/	User-specific branding assets

When useradd -m creates an account, these files copy automatically. The omarchy finalize user command then runs once per user to:

• Create required symlinks
• Execute xdg-user-dirs-update
• Enable user systemd services
• Apply runtime-dependent tweaks

Refresh a single config file to its shipped default:

omarchy-refresh-config hypr/hyprland.lua

# Copies from $OMARCHY_PATH/config/hypr/hyland.lua → $HOME/.config/hypr/hyprland.lua

System-Wide Drop-ins: Direct /etc/ Installation

Files under etc/ and default/ install directly into system configuration paths, bypassing /usr/share/omarchy/.

Repository Path	Installed Location	Function
etc/fastfetch/config.jsonc	/etc/fastfetch/config.jsonc	System-wide Fastfetch configuration
etc/mkinitcpio.conf.d/omarchy_hooks.conf	/etc/mkinitcpio.conf.d/omarchy_hooks.conf	Boot hooks
etc/profile.d/omarchy.sh	/etc/profile.d/omarchy.sh	Shell environment
default/limine/*	/usr/share/omarchy/default/limine/	Bootloader templates for ISO generation
default/snapper/root	/etc/snapper/config-templates/omarchy	Btrfs snapshot configuration template

Verify a system-wide drop-in:

cat /etc/profile.d/omarchy.sh

# → content originates from default/bashrc transformation

Default Resources and Theming System

The default/ directory contains heterogeneous resources scattered across FHS-compliant locations:

• Systemd units: /usr/lib/systemd/user/
• Font configuration: /usr/share/fontconfig/conf.avail/
• Custom fonts: /usr/share/fonts/omarchy/
• SDDM theme: /usr/share/sddm/themes/omarchy/
• Wayland sessions: /usr/local/share/wayland-sessions/
• Application icons: /usr/share/icons/hicolor/{48,256,scalable}/apps/

Repository Asset	Installed Locations
logo.{txt,svg}	/usr/share/omarchy/, branding directories
icon.{txt,png}	/usr/share/pixmaps/omarchy.png, /usr/share/icons/hicolor/256x256/apps/omarchy.png
default/applications/battlenet.desktop	/usr/share/omarchy/default/applications/ (installer-only template)

The Three-Stage Provisioning Model

Omarchy's file layout supports a complete user lifecycle:

1. Seed — /etc/skel/ files copy automatically on account creation
2. Finalize — omarchy finalize user completes per-user setup once
3. Resync — omarchy-reinstall-configs restores defaults for existing users by re-copying current /etc/skel/ contents

This design separates static system files (managed by pacman, never touched after install) from per-user configuration (safely regenerable or overrideable).

Restore all default configs:

omarchy-reinstall-configs

# Overwrites ~/.config/ and ~/.local/share/applications/ with /etc/skel/ contents

Key Source Files for Reference

Path in Repository	Documentation Role
docs/file-layout.md	Authoritative mapping specification
bin/omarchy-*	Runtime command implementations
config/**	User-side default configurations
default/**	System-wide resource templates
install/**	System installation automation
etc/**	Direct /etc/ drop-in sources
themes/**	Bundled visual themes
migrations/**	Upgrade migration scripts

Summary

• Omarchy's repository splits into omarchy (runtime) and omarchy-settings (configuration) packages at build time
• Binaries from bin/omarchy-* install to /usr/bin/ with copies at /usr/share/omarchy/bin/
• Static resources (themes/, shell/, install/, migrations/) land under /usr/share/omarchy/
• User defaults seed via /etc/skel/ from config/ and applications/, finalized by omarchy finalize user
• System drop-ins from etc/ and default/ install directly to /etc/ and other FHS locations
• The three-stage model (seed, finalize, resync) enables reproducible, recoverable user environments

Frequently Asked Questions

Where does Omarchy store its themes after installation?

Stock themes live at /usr/share/omarchy/themes/ with subdirectories matching repository names like white and vantablack. This path is read-only; user theme overrides belong in ~/.config/omarchy/themes/.

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

omarchy-settings installs first and contains skeleton files, system drop-ins, and debug tools needed before the main package. omarchy provides the runtime, themes, and upgrade infrastructure. You can inspect the package split in docs/file-layout.md as implemented in basecamp/omarchy.

How do I restore Omarchy's default configurations without reinstalling?

Run omarchy-reinstall-configs to copy current /etc/skel/ contents over your home directory, then omarchy finalize user if needed. This resyncs your dotfiles to the version shipped with your installed package.

Why are some files in /etc/skel/ and others in /usr/share/omarchy/?

/etc/skel/ contains files copied once per new user (personal configs, application launchers). /usr/share/omarchy/ holds system-wide, read-only resources used by all users. The separation follows the FHS pattern: skeleton files for user provisioning, /usr/share/ for static application data.

Where can I find the authoritative documentation for file mappings?

The docs/file-layout.md file in the basecamp/omarchy repository contains the complete, versioned mapping table maintained alongside the source code. This document is the single source of truth for build system behavior.

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