What Is the OMARCHY_PATH Environment Variable in Omarchy?

OMARCHY_PATH is the single source of truth that tells the Omarchy stack where its installation root lives, established during login-shell startup and consumed by shell scripts, Quickshell QML runtime, and systemd services.

OMARCHY_PATH serves as the foundation of Omarchy's runtime environment. Whether you're running a stable release from /usr/share/omarchy or developing against a local checkout, this environment variable ensures every component—from shell utilities to the UI layer—locates the correct resources. According to the basecamp/omarchy source code, it is set early in the shell initialization chain and propagates through the entire stack.

How OMARCHY_PATH Is Set at Runtime

System-Wide Configuration via /etc/omarchy.conf

The bootstrap sequence in default/bash/env-bootstrap (lines 7-15) determines the value of OMARCHY_PATH before any Omarchy commands execute:

# 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

If /etc/omarchy.conf exists, it is sourced and may override the default. Otherwise, the packaged installation path /usr/share/omarchy is used. The ${var:=default} syntax ensures that if the variable is unset or empty after sourcing the config, the fallback applies.

Development Mode with omarchy-dev-link

For developers working on Omarchy itself, the omarchy-dev-link utility redirects OMARCHY_PATH to a source checkout. When you run:

omarchy-dev-link /path/to/omarchy-checkout

The script writes the checkout directory to /etc/omarchy.conf (lines 102-106 in bin/omarchy-dev-link):

# bin/omarchy-dev-link (excerpt)

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

New login shells then automatically pick up the development path. To restore packaged behavior, run omarchy-dev-unlink, which removes or resets /etc/omarchy.conf.

PATH Adjustment for Development

When OMARCHY_PATH differs from the default packaged location, the bootstrap script ensures your checkout's binaries take precedence. Lines 21-26 of default/bash/env-bootstrap handle this:

# 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

This prepends $OMARCHY_PATH/bin to PATH only if not already present, ensuring that modified omarchy-* commands shadow their installed counterparts.

Where OMARCHY_PATH Is Used at Runtime

Shell Scripts and Configuration Management

Every Omarchy command relies on OMARCHY_PATH to locate its resources. The omarchy-refresh-config utility demonstrates this pattern (lines 30-35 of bin/omarchy-refresh-config):

# bin/omarchy-refresh-config (excerpt)

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

This copies default configuration files from the Omarchy tree into the user's home directory, enabling both initial setup and reset-to-default operations.

Quickshell QML UI Runtime

The graphical interface built on Quickshell accesses OMARCHY_PATH at runtime via Quickshell.env(). From test/shell.d/fixtures/manifest-entrypoints/shell.qml (lines 8-9):

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

QML components use this path to load widgets, icons, and other assets relative to the installation root.

Hyprland and Lua Bootstrap Integration

When Omarchy launches a Hyprland session, the Lua bootstrap explicitly depends on OMARCHY_PATH (excerpt from test/shell.d/hyprland-workspace-layout-test.sh, lines 62-63):

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

This mechanism loads session-specific configuration and keybindings, ensuring the desktop environment initializes with Omarchy's defaults.

Systemd Service Conditions

Systemd unit files use ConditionEnvironment to gate service startup on the presence of OMARCHY_PATH. The test suite verifies this behavior in test/shell.d/systemd-test.sh (line 23):

# Verified pattern in sleep-monitor service

ConditionEnvironment=OMARCHY_PATH

This prevents services from running in environments where Omarchy has not been properly initialized.

Practical Examples

Manual Override for Testing

export OMARCHY_PATH="/home/user/omarchy"
source /usr/share/omarchy/default/bash/env-bootstrap
omarchy-refresh-config hypr/bindings.lua   # pulls from the overridden tree

QML Component Access

Item {
    property string omarchyRoot: Quickshell.env("OMARCHY_PATH")
    // Load a QML fragment from the Omarchy tree
    Loader { source: omarchyRoot + "/default/qml/some-widget.qml" }
}

Development Workflow

omarchy-dev-link /path/to/omarchy-checkout   # writes /etc/omarchy.conf

# New shells automatically see OMARCHY_PATH point at the checkout

echo "$OMARCHY_PATH"                         # → /path/to/omarchy-checkout

Key Source Files

Purpose	File Path
Core bootstrap defining OMARCHY_PATH	default/bash/env-bootstrap
Dev-link helper writing /etc/omarchy.conf	bin/omarchy-dev-link
Dev-unlink helper restoring defaults	bin/omarchy-dev-unlink
QML runtime access pattern	test/shell.d/fixtures/manifest-entrypoints/shell.qml
Lua bootstrap usage	test/shell.d/hyprland-workspace-layout-test.sh
Systemd condition verification	test/shell.d/systemd-test.sh

Summary

• OMARCHY_PATH is the canonical pointer to Omarchy's installation root, set during shell initialization and exported to all child processes.
• Dynamic resolution: Defaults to /usr/share/omarchy, overridable via /etc/omarchy.conf for development workflows.
• Cross-layer propagation: Used by Bash scripts, Quickshell QML, Lua bootstraps, and systemd services.
• Development ergonomics: omarchy-dev-link and omarchy-dev-unlink provide seamless switching between packaged and source-tree installations.
• Runtime dependency: Multiple components fail gracefully or refuse to start if the variable is undefined.

Frequently Asked Questions

What happens if OMARCHY_PATH is not set?

Omarchy components that depend on the variable will behave incorrectly or refuse to start. Systemd services with ConditionEnvironment=OMARCHY_PATH will remain inactive, and scripts that reference $OMARCHY_PATH will expand it to an empty string, causing file-not-found errors.

Can I set OMARCHY_PATH manually without using omarchy-dev-link?

Yes. You can export the variable in your shell profile or set it inline before sourcing default/bash/env-bootstrap. However, omarchy-dev-link is recommended because it also manages /etc/omarchy.conf and PATH adjustments consistently.

How does OMARCHY_PATH differ from a standard installation prefix like /usr?

Unlike a static prefix, OMARCHY_PATH is determined at login time and can switch between packaged and development trees without reinstallation. It also triggers runtime PATH modifications and is introspectable by the Quickshell UI layer.

Is OMARCHY_PATH required for all Omarchy users, or only developers?

All users require OMARCHY_PATH, though most receive it automatically through default/bash/env-bootstrap. The default value /usr/share/omarchy handles standard installations transparently, while the development workflow provides explicit control for contributors.

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