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

> Discover how the OMARCHY_PATH environment variable is set during login and used by scripts, QML, and systemd to find Omarchy files. Learn its crucial role in the runtime environment.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-19

---

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

```sh

# 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](https://github.com/basecamp/omarchy/blob/quattro/default/bash/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`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf). This redirects `OMARCHY_PATH` to point at the source tree rather than the system installation.

```sh

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

```sh

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

```sh

# bin/omarchy-refresh-config (excerpt)

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

```

(Source: [omarchy‑refresh‑config L30‑L35](https://github.com/basecamp/omarchy/blob/quattro/bin/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.

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

```

(Source: [manifest‑entrypoints L8‑L9](https://github.com/basecamp/omarchy/blob/quattro/test/shell.d/fixtures/manifest-entrypoints/shell.qml#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.

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

```

(Source: [hyprland‑bootstrap L62‑L63](https://github.com/basecamp/omarchy/blob/quattro/test/shell.d/hyprland-workspace-layout-test.sh#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.

```ini

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

ConditionEnvironment=OMARCHY_PATH

```

(Source: [systemd‑test L23](https://github.com/basecamp/omarchy/blob/quattro/test/shell.d/systemd-test.sh#L23))

## Practical Configuration Examples

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

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

```

**QML access within a Quickshell component:**

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

```

**Development workflow using dev-link:**

```bash
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`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf).
- The `omarchy-dev-link` utility redirects the variable to a development checkout by writing to [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//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`](https://github.com/basecamp/omarchy/blob/main//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`](https://github.com/basecamp/omarchy/blob/main//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`](https://github.com/basecamp/omarchy/blob/main//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.