How Omarchy Is Structured: The Two-Package Architecture Explained

Omarchy uses a two-package mental model that separates runtime binaries from system-wide defaults, deploying three distinct layers to populate user home directories.

Omarchy is an open-source desktop environment by Basecamp built on Arch Linux. Understanding how Omarchy is structured requires looking at its unique packaging strategy and the three-layer system it uses to manage user configurations from initial install through ongoing updates.

The Two-Package Mental Model

The architecture cleanly splits functionality between two distinct packages to ensure system defaults exist before the runtime environment is installed.

The omarchy Package

This package contains the runtime environment. It ships binaries, themes, and the Quickshell desktop definition:

• Runtime binaries live in bin/ and install to /usr/bin/omarchy-* with symlinks under /usr/share/omarchy/bin/
• Installation scripts in install/ handle system-wide configuration
• Migrations in migrations/ provide incremental upgrade scripts
• Desktop shell components in shell/ define the Quickshell UI
• Themes in themes/ provide built-in visual defaults

The omarchy-settings Package

This package contains all files that must exist before the main omarchy package installs:

• /etc/skel/ templates that useradd -m copies into new user home directories
• System-wide drop-ins under /etc/ for system configuration
• Shared data under /usr/share including fonts, Plymouth themes, and SDDM themes
• Debug utilities (omarchy-debug* binaries) for troubleshooting

Post-install scripts copy these seeds from the package into the target root filesystem, ensuring defaults are present before any user accounts are created.

Three-Layer User Home Population

Omarchy populates user homes through a deliberate three-phase process documented in docs/file-layout.md.

1. Seed

The omarchy-settings package ships static defaults to /etc/skel/. When administrators create new users with useradd -m, Arch Linux copies this entire tree into the user's $HOME.

2. Finalize

The command omarchy provision-user (routed internally as omarchy finalize user) runs once per user after the seed step. Unlike static seed files, this step performs runtime-specific tasks:

• Expanding $HOME-dependent paths that cannot be hardcoded in /etc/skel/
• Detecting current hardware state (e.g., GPU mode)
• Installing user-specific themes or plugins

This executes the script located at bin/omarchy-provision-user in the repository.

3. Resync

Existing users can reset configurations to shipped defaults using omarchy reinstall-configs. This command deliberately overwrites $HOME/.config/omarchy/* with fresh copies from /usr/share/omarchy/config/, allowing users to recover from broken customizations while preserving their data.

Repository-to-Filesystem Mapping

During the build process, the repository layout maps to specific installation paths:

• bin/omarchy-* → /usr/bin/omarchy-* (and symlinks in /usr/share/omarchy/bin/)
• install/** → /usr/share/omarchy/install/
• migrations/** → /usr/share/omarchy/migrations/
• themes/** → /usr/share/omarchy/themes/
• shell/** → /usr/share/omarchy/shell/
• config/** → /etc/skel/.config/** (for new users) and /usr/share/omarchy/config/** (resync source)
• default/** → System-wide locations including /etc/skel/.bashrc and /etc/fastfetch/config.jsonc

The file docs/file-layout.md in the repository contains the complete authoritative map of these transformations.

Environment Bootstrap and Runtime Paths

All entry points source a single bootstrap script: default/bash/env-bootstrap. This script:

1. Reads /etc/omarchy.conf (written by omarchy-dev-link) or defaults OMARCHY_PATH to /usr/share/omarchy
2. Prepends $OMARCHY_PATH/bin to $PATH only when a development link is active
3. Adds Mise tool directories ($HOME/.local/share/mise/shims and $HOME/.local/bin) for user-installed tools

This bootstrap is referenced from /etc/profile.d/omarchy.sh, user shells, the uwsm session manager, and SSH non-login shells.

Where Themes and State Live

User-specific data follows XDG conventions to separate ephemeral state from version-controllable configuration:

• Generated theme state: ~/.local/state/omarchy/current/
• Persistent user configuration: ~/.config/omarchy/

This separation allows users to track customizations in Git while still being able to resync core defaults when needed.

Common Operations

Below are commands that demonstrate working with the Omarchy structure:

# List all available omarchy commands

omarchy help --list

# Run per-user finalization (typically once after install)

omarchy provision-user

# Reset user config to shipped defaults

omarchy reinstall-configs

# View the environment bootstrap script

cat /usr/share/omarchy/default/bash/env-bootstrap

# Inspect a migration script

cat /usr/share/omarchy/migrations/1782049344.sh

Summary

• Omarchy ships runtime binaries and the Quickshell desktop, while omarchy-settings provides system-wide defaults and /etc/skel/ templates.
• User homes populate via three layers: Seed (static files from /etc/skel/), Finalize (runtime omarchy provision-user), and Resync (omarchy reinstall-configs).
• The file default/bash/env-bootstrap serves as the single source of truth for OMARCHY_PATH and environment setup across all entry points.
• User state lives under ~/.local/state/omarchy/current/ and configuration under ~/.config/omarchy/, enabling safe resyncs without data loss.

Frequently Asked Questions

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

The omarchy package contains the runtime binaries, themes, and Quickshell desktop found in bin/, shell/, and themes/. The omarchy-settings package contains files that must exist before Omarchy runs, including /etc/skel/ templates, system-wide /etc/ drop-ins, fonts, and the three debug binaries (omarchy-debug*). This separation ensures defaults are present before the main software installs.

When should I run omarchy provision-user?

Run omarchy provision-user once per user after the initial installation or when creating a new user account. This command handles tasks that cannot be performed by the static seed step, such as expanding $HOME paths, detecting current GPU hardware, and installing user-specific plugins or themes that require the live $OMARCHY_PATH.

How do I reset my Omarchy configuration without reinstalling the OS?

Use the omarchy reinstall-configs command. This destroys the contents of ~/.config/omarchy/* and replaces them with the default files shipped in /usr/share/omarchy/config/. Your generated theme state in ~/.local/state/omarchy/ remains untouched, allowing you to recover from configuration errors while preserving runtime data.

Where is OMARCHY_PATH defined and how does it affect the system?

OMARCHY_PATH is defined in default/bash/env-bootstrap, which reads /etc/omarchy.conf or defaults to /usr/share/omarchy. This bootstrap script is sourced by /etc/profile.d/omarchy.sh, user shells, and the uwsm session manager. When active development links exist, the script prepends $OMARCHY_PATH/bin to $PATH, otherwise it ensures tools installed via Mise are available by adding $HOME/.local/share/mise/shims to the path.

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