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

> Learn what OMARCHY_PATH is and how it's set in the Omarchy desktop environment. Discover its role in specifying active Omarchy checkout paths for seamless development.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-08

---

**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:

```bash
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:

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

```

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

```bash
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`](https://github.com/omacom/omarchy/blob/main/default/hypr/bootstrap.lua) is executed via:

```lua
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`](https://github.com/omacom/omarchy/blob/main/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:

```bash

# 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:

```bash
[[ -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.