# What Is the OMARCHY_PATH Environment Variable in Omarchy?

> Understand the OMARCHY_PATH environment variable in Omarchy. Learn how it defines the installation root for scripts, runtime, and services, ensuring a unified Omarchy stack.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-20

---

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

```bash

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

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

```

The script writes the checkout directory to [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) (lines 102-106 in `bin/omarchy-dev-link`):

```bash

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

```bash

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

```bash

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

```qml
// 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`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/hyprland-workspace-layout-test.sh), lines 62-63):

```lua
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`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/systemd-test.sh) (line 23):

```ini

# 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

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

```qml
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

```bash
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`](https://github.com/basecamp/omarchy/blob/main//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`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/hyprland-workspace-layout-test.sh) |
| Systemd condition verification | [`test/shell.d/systemd-test.sh`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main//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`](https://github.com/basecamp/omarchy/blob/main//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.