How the OMARCHY_PATH Environment Variable Is Set and Used at Runtime in Omarchy

The OMARCHY_PATH environment variable serves as the single source of truth for the Omarchy installation root, initialized during login-shell startup via /etc/omarchy.conf or defaulted to /usr/share/omarchy, then consumed by shell scripts, Quickshell QML components, and systemd units to locate configuration files, binaries, and desktop assets.

Omarchy is Basecamp's open-source Linux desktop environment built on Hyprland and Quickshell. The OMARCHY_PATH environment variable acts as the canonical pointer to the installation directory, enabling both system-wide deployments and local development workflows. Understanding how this variable is established and referenced is essential for customizing or contributing to the basecamp/omarchy codebase.

How OMARCHY_PATH Is Initialized at Login

The variable is established early in the login-shell startup chain through a cascade of configuration checks that distinguish between production installations and development checkouts.

System-Wide Configuration via /etc/omarchy.conf

The primary bootstrap logic resides in default/bash/env-bootstrap, which checks for the existence of /etc/omarchy.conf. If present, the script sources it to obtain the custom path; otherwise, it falls back to the packaged location at /usr/share/omarchy.

# default/bash/env-bootstrap

if [ -f /etc/omarchy.conf ]; then
  . /etc/omarchy.conf
  : "${OMARCHY_PATH:=/usr/share/omarchy}"
else
  OMARCHY_PATH=/usr/share/omarchy
fi
export OMARCHY_PATH

This ensures that OMARCHY_PATH is always exported to the environment, regardless of whether a custom configuration exists (Source: env‑bootstrap L7‑L15).

Development Mode with omarchy-dev-link

When developers run the omarchy-dev-link command, the script writes the absolute path of the checkout directory into /etc/omarchy.conf. This redirects OMARCHY_PATH to point at the source tree rather than the system installation.

# bin/omarchy-dev-link (excerpt)

printf 'export OMARCHY_PATH="%s"\n' "$checkout" | sudo tee /etc/omarchy.conf >/dev/null

(Source: omarchy‑dev‑link L102‑L106)

PATH Adjustment for Development Checkouts

If OMARCHY_PATH differs from the standard /usr/share/omarchy location, the bootstrap script automatically prepends the checkout's bin directory to $PATH. This ensures that development binaries shadow the installed ones without manual PATH manipulation.

# default/bash/env-bootstrap (excerpt)

if [ "$OMARCHY_PATH" != /usr/share/omarchy ]; then
  case ":$PATH:" in
    *":${OMARCHY_PATH%/}/bin:"*) ;;
    *) PATH="${OMARCHY_PATH%/}/bin${PATH:+:$PATH}" ;;
  esac
fi
export PATH

(Source: env‑bootstrap L21‑L26)

Runtime Utilization of OMARCHY_PATH

Once established, OMARCHY_PATH is consumed across multiple runtime contexts to resolve resource locations dynamically.

Shell Script Resource Location

Every Omarchy command and helper script uses OMARCHY_PATH to locate configuration templates and default modules. For example, omarchy-refresh-config copies files from the installation tree into the user's home directory.

# bin/omarchy-refresh-config (excerpt)

src="${OMARCHY_PATH}/config/${cfg}"
cp -r "$src" "$HOME/.config/${cfg}"

(Source: omarchy‑refresh‑config L30‑L35)

Quickshell QML Runtime Access

The Quickshell UI runtime retrieves the variable via Quickshell.env("OMARCHY_PATH"). This allows QML files to load Lua bootstrap scripts, icons, and other assets using absolute paths derived from the installation root.

// test/shell.d/fixtures/manifest-entrypoints/shell.qml
readonly property string rootPath: Quickshell.env("OMARCHY_PATH")

(Source: manifest‑entrypoints L8‑L9)

Hyprland and Lua Bootstrapping

When Omarchy launches a Hyprland session, the QML code executes a Lua bootstrap that explicitly concatenates the environment variable with the path to the default Hyprland scripts.

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

(Source: hyprland‑bootstrap L62‑L63)

Systemd Service Conditions

Systemd unit files include ConditionEnvironment=OMARCHY_PATH to ensure services only start when the variable is defined in the environment. This prevents execution failures in contexts where the Omarchy stack has not been properly initialized.

# Verified in test/shell.d/systemd-test.sh

ConditionEnvironment=OMARCHY_PATH

(Source: systemd‑test L23)

Practical Configuration Examples

The following patterns demonstrate common workflows for overriding or accessing OMARCHY_PATH in different contexts.

Manual override for testing:

export OMARCHY_PATH="/home/user/omarchy"
source /usr/share/omarchy/default/bash/env-bootstrap
omarchy-refresh-config hypr/bindings.lua

QML access within a Quickshell component:

Item {
    property string omarchyRoot: Quickshell.env("OMARCHY_PATH")
    Loader { source: omarchyRoot + "/default/qml/some-widget.qml" }
}

Development workflow using dev-link:

omarchy-dev-link /path/to/omarchy-checkout
echo "$OMARCHY_PATH"

# Output: /path/to/omarchy-checkout

Summary

• OMARCHY_PATH is defined in default/bash/env-bootstrap and defaults to /usr/share/omarchy unless overridden by /etc/omarchy.conf.
• The omarchy-dev-link utility redirects the variable to a development checkout by writing to /etc/omarchy.conf and adjusting $PATH accordingly.
• Shell scripts reference $OMARCHY_PATH to locate configuration files, while Quickshell QML accesses it via Quickshell.env("OMARCHY_PATH") for UI assets.
• Systemd units use ConditionEnvironment=OMARCHY_PATH to gate service startup on the variable's presence.

Frequently Asked Questions

What is the default value of OMARCHY_PATH if /etc/omarchy.conf is missing?

If /etc/omarchy.conf does not exist, the bootstrap script in default/bash/env-bootstrap sets OMARCHY_PATH to /usr/share/omarchy. This default corresponds to the standard system-wide installation path used by package managers.

How does omarchy-dev-link affect the OMARCHY_PATH variable?

The omarchy-dev-link command writes an export OMARCHY_PATH="/path/to/checkout" statement into /etc/omarchy.conf. Subsequent login shells source this file during bootstrap, causing the variable to point at the development tree instead of /usr/share/omarchy, while also prepending the checkout's bin directory to $PATH.

Can OMARCHY_PATH be changed after login?

While you can manually export a new value in an existing shell, systemic changes require updating /etc/omarchy.conf and starting a new login shell to re-execute default/bash/env-bootstrap. Systemd user services may require a daemon reload or logout/login cycle to see the updated value, as they inherit the environment from the user manager.

How does Quickshell access OMARCHY_PATH at runtime?

Quickshell QML files call Quickshell.env("OMARCHY_PATH") to retrieve the string value. This method is used throughout the UI layer to construct absolute paths for loading Lua bootstrap scripts, icon themes, and other runtime assets relative to the Omarchy installation root.

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