How Omarchy Defines Its Core Runtime Path Using OMARCHY_PATH

Omarchy centralizes its installation root in the OMARCHY_PATH environment variable, defined in default/bash/env-bootstrap and exported to every shell session.

The OMARCHY_PATH environment variable serves as the single source of truth for Omarchy's installation directory, enabling consistent resource resolution across CLI tools, QML shells, and system provisioning scripts. In the basecamp/omarchy repository, this variable is established once during shell initialization and propagated to all child processes.

OMARCHY_PATH Initialization in the Bootstrap Script

The Primary Source: default/bash/env-bootstrap

In default/bash/env-bootstrap, the Omarchy bootstrap script conditionally sets OMARCHY_PATH based on the presence of a system configuration file. This file is sourced by every login shell, user session, and uwsm environment.

The logic follows a two-step fallback pattern:

• Configuration file check – If /etc/omarchy.conf exists (typically written by omarchy-dev-link), the script sources it, allowing the file to define OMARCHY_PATH.
• Default fallback – If the configuration is absent, the variable is forced to the packaged default.

# From default/bash/env-bootstrap

if [ -f /etc/omarchy.conf ]; then
  . /etc/omarchy.conf
else
  OMARCHY_PATH=/usr/share/omarchy
fi
export OMARCHY_PATH

Development Mode PATH Adjustment

When OMARCHY_PATH points to a development checkout (any path other than /usr/share/omarchy), the bootstrap script automatically prepends Omarchy's bin directory to the system PATH. This ensures development binaries take precedence without manual configuration.

if [ "$OMARCHY_PATH" != /usr/share/omarchy ]; then
  PATH="${OMARCHY_PATH%/}/bin${PATH:+:$PATH}"
fi

Consuming OMARCHY_PATH Across the Codebase

All Omarchy commands read OMARCHY_PATH to locate configuration files, plugins, themes, and internal scripts. The codebase consistently uses a shell parameter expansion pattern to provide a safe default when the variable is unset.

In bin/omarchy-shell, bin/omarchy-provision-user, and bin/omarchy-version, you will find this defensive reference pattern:

omarchy_path=${OMARCHY_PATH:-/usr/share/omarchy}

This approach guarantees that even if the bootstrap script is bypassed, components default to the system-wide installation at /usr/share/omarchy.

Practical Usage Examples

Verifying the Current Runtime Path

Check the active Omarchy installation root from any shell:

echo "$OMARCHY_PATH"

Output:

/usr/share/omarchy

Switching to a Development Checkout

To run Omarchy from a local git repository, export the path to your checkout before launching the shell:

export OMARCHY_PATH="$HOME/src/omarchy"
omarchy-shell

The env-bootstrap logic automatically prepends $OMARCHY_PATH/bin to your PATH, ensuring the checkout's binaries are used.

Accessing Resources in Shell Scripts

When writing scripts that depend on Omarchy internals, source the bootstrap file and reference files relative to the variable:

#!/usr/bin/env bash
source "/etc/profile.d/omarchy.sh"

config_file="${OMARCHY_PATH}/config/omarchy/shell.json"
jq '.' "$config_file"

Reading the Path in QML Components

Quickshell-based UIs can access the runtime path through environment introspection:

// In a QML fixture
readonly property string rootPath: Quickshell.env("OMARCHY_PATH")

Summary

• OMARCHY_PATH is defined centrally in default/bash/env-bootstrap and exported to all shell sessions.
• The variable defaults to /usr/share/omarchy unless overridden by /etc/omarchy.conf.
• Development checkouts trigger automatic PATH prepending when OMARCHY_PATH differs from the system default.
• All Omarchy utilities consume this variable using the ${OMARCHY_PATH:-/usr/share/omarchy} pattern to locate resources reliably.
• The mechanism supports both system-wide installations and development workflows without code changes.

Frequently Asked Questions

What happens if OMARCHY_PATH is not set?

If OMARCHY_PATH is undefined, Omarchy binaries fall back to /usr/share/omarchy using shell parameter expansion (${OMARCHY_PATH:-/usr/share/omarchy}). This ensures the system package installation remains functional even if the bootstrap script is not sourced.

How do I use a development checkout of Omarchy?

Create or edit /etc/omarchy.conf to set OMARCHY_PATH to your git checkout directory, or export the variable manually in your shell. When the path differs from /usr/share/omarchy, the env-bootstrap script automatically prepends $OMARCHY_PATH/bin to your PATH, allowing you to test local changes immediately.

Where is OMARCHY_PATH defined for system-wide sessions?

The definition originates in default/bash/env-bootstrap within the repository. This script is sourced by system-wide configuration files such as /etc/profile.d/omarchy.sh, making the variable available to all login shells, user ~/.bashrc configurations, and uwsm sessions.

Can OMARCHY_PATH be used in QML/Quickshell components?

Yes. Quickshell plugins can read the environment variable using Quickshell.env("OMARCHY_PATH"), allowing QML components to resolve absolute paths to themes, configuration files, and internal resources relative to the Omarchy installation root.

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