What Is OMARCHY_PATH and How Is It Determined in the Omarchy Desktop Environment?

OMARCHY_PATH is an environment variable that specifies the absolute path to the active Omarchy checkout, set either by the session manager during system installation or manually in development environments.

The omacom/omarchy repository uses OMARCHY_PATH as the single source of truth for locating shared resources. Every shell script, QML bootstrap file, and configuration loader references this variable to find themes, default configs, and command-line utilities within the repository structure.

Why OMARCHY_PATH Matters

OMARCHY_PATH serves as the root anchor for the entire Omarchy runtime. When you execute any omarchy-* command, the script looks for dependencies relative to this path rather than using hardcoded locations. This design allows the same codebase to function as a system-wide installation under /usr/share/omarchy or as a live development checkout in your home directory.

The variable enables portable execution—scripts resolve paths like "$OMARCHY_PATH/bin/omarchy-update-dev" or "$OMARCHY_PATH/default/hypr/bootstrap.lua" dynamically. Without this environment variable, components cannot locate the QML shell bootstrap, theme directories, or the bin/ directory containing utilities.

How OMARCHY_PATH Is Determined

The value of OMARCHY_PATH is populated through three distinct mechanisms depending on your deployment scenario.

System Installation via uwsm

For package installations, the session manager (uwsm) injects OMARCHY_PATH=/usr/share/omarchy before launching any Omarchy process. This points to the read-only location where distribution packages install the files. In shell/shell.qml, the environment variable is inherited directly from the uwsm-launched session, ensuring the QML bootstrap loads resources from the system path.

Development Checkouts

When working from a cloned repository, you must explicitly export the variable to point to your working tree. The bin/omarchy-dev wrapper handles this automatically when you run omarchy-dev link, setting:

OMARCHY_PATH="$(realpath "$(git rev-parse --show-toplevel)")"
export OMARCHY_PATH

The test harness in test/shell.d/ also sets OMARCHY_PATH="$ROOT" where $ROOT refers to a temporary checkout, ensuring test isolation from your main installation.

Manual Override and Safety Checks

Users may override OMARCHY_PATH manually before invoking commands. However, Omarchy implements strict validation guards. Every script in bin/ starts with a compatibility check:

[[ -n ${OMARCHY_PATH:-} ]] || fail "OMARCHY_PATH is not set"

Additionally, commands like bin/omarchy-update-dev verify the path represents an actual git repository:

if [[ ! -d "$OMARCHY_PATH/.git" ]]; then
    echo "Error: OMARCHY_PATH is not a git checkout" >&2
    exit 1
fi

This prevents accidental execution of mutable scripts from untrusted directories.

Where OMARCHY_PATH Is Used in the Codebase

The variable permeates the Omarchy architecture across shell scripts, Lua configurations, and QML interfaces.

Shell Bootstrap and Command Dispatch

In bin/omarchy-shell, the entry point checks OMARCHY_PATH and immediately prepends $OMARCHY_PATH/bin to the PATH environment variable. This ensures all subsidiary omarchy commands resolve without absolute paths. The Hyprland bootstrap loader in default/hypr/bootstrap.lua is executed via:

dofile(os.getenv("OMARCHY_PATH") .. "/default/hypr/bootstrap.lua")

Menu Generation and Configuration

The menu system reads static configurations from $OMARCHY_PATH/config/, allowing themes and keybinding definitions to reside within the version-controlled repository while being accessed by runtime components.

Test Isolation

The test suite explicitly exports OMARCHY_PATH="$ROOT" at the beginning of each test case (as seen in test/shell.d/version-test.sh). This guarantees that test executions use the temporary test checkout rather than interfering with a system installation or user development environment.

Working with OMARCHY_PATH

Inspect and manipulate the variable using standard shell commands:

# Display the current Omarchy root

echo "$OMARCHY_PATH"

# Output: /usr/share/omarchy

# Run commands from a local clone without system installation

cd ~/projects/omarchy
export OMARCHY_PATH="$(pwd)"
./bin/omarchy-theme-list

# Verify you are using a development checkout

if [[ -d "$OMARCHY_PATH/.git" ]]; then
    echo "Development mode: $(git -C "$OMARCHY_PATH" describe --tags)"
else
    echo "System installation (read-only)"
fi

When developing new Omarchy components, always reference resources through "$OMARCHY_PATH" rather than relative paths to ensure compatibility across installation types.

Summary

• OMARCHY_PATH is the canonical environment variable pointing to the active Omarchy checkout root.
• System installations receive the variable from uwsm set to /usr/share/omarchy.
• Development environments must manually export the variable to the repository root, typically handled by bin/omarchy-dev.
• Mandatory validation occurs in all shell scripts via [[ -n ${OMARCHY_PATH:-} ]] checks, with git repository verification in development tools.
• Key source files implementing this logic include bin/omarchy-shell, bin/omarchy-update-dev, shell/shell.qml, and test harnesses in test/shell.d/.

Frequently Asked Questions

What happens if OMARCHY_PATH is not set?

Any Omarchy command will abort immediately with the error message "OMARCHY_PATH is not set". The guard clause [[ -n ${OMARCHY_PATH:-} ]] || fail "OMARCHY_PATH is not set" appears at the top of every executable script in bin/ to prevent execution in undefined environments.

Can I run Omarchy commands from any directory?

Yes, provided OMARCHY_PATH is correctly exported. Because scripts resolve resources using "$OMARCHY_PATH" rather than relative paths like "./config", you can execute omarchy-update-dev or similar commands from any working directory once the environment variable points to a valid checkout.

How do I verify my OMARCHY_PATH points to a valid checkout?

Check for the presence of a .git directory and the expected binary structure:

[[ -d "$OMARCHY_PATH/.git" ]] && [[ -x "$OMARCHY_PATH/bin/omarchy-shell" ]] && echo "Valid"

If you intend to run development commands like omarchy-update-dev, the git check is mandatory—the script will refuse to run if OMARCHY_PATH points to a plain directory without version control.

Does OMARCHY_PATH differ between stable and development builds?

The variable structure remains identical, but the value changes based on installation method. Stable system builds use OMARCHY_PATH=/usr/share/omarchy (read-only), while development builds use the absolute path to your git clone. Both formats expect the same directory structure containing bin/, default/, shell/, and config/ subdirectories.

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