# How Omarchy Defines Its Core Runtime Path Using OMARCHY_PATH

> Learn how Omarchy defines its core runtime path using the OMARCHY_PATH environment variable. Discover how this centralizes installation for every shell session in the Omarchy project.

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

---

**Omarchy centralizes its installation root in the `OMARCHY_PATH` environment variable, defined in `default/bash/env-bootstrap` and exported to every shell session.**

The `OMARCHY_PATH` environment variable serves as the single source of truth for Omarchy's installation directory, enabling consistent resource resolution across CLI tools, QML shells, and system provisioning scripts. In the basecamp/omarchy repository, this variable is established once during shell initialization and propagated to all child processes.

## OMARCHY_PATH Initialization in the Bootstrap Script

### The Primary Source: default/bash/env-bootstrap

In `default/bash/env-bootstrap`, the Omarchy bootstrap script conditionally sets `OMARCHY_PATH` based on the presence of a system configuration file. This file is sourced by every login shell, user session, and uwsm environment.

The logic follows a two-step fallback pattern:

- **Configuration file check** – If [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) exists (typically written by `omarchy-dev-link`), the script sources it, allowing the file to define `OMARCHY_PATH`.
- **Default fallback** – If the configuration is absent, the variable is forced to the packaged default.

```bash

# From default/bash/env-bootstrap

if [ -f /etc/omarchy.conf ]; then
  . /etc/omarchy.conf
else
  OMARCHY_PATH=/usr/share/omarchy
fi
export OMARCHY_PATH

```

### Development Mode PATH Adjustment

When `OMARCHY_PATH` points to a development checkout (any path other than `/usr/share/omarchy`), the bootstrap script automatically prepends Omarchy's `bin` directory to the system `PATH`. This ensures development binaries take precedence without manual configuration.

```bash
if [ "$OMARCHY_PATH" != /usr/share/omarchy ]; then
  PATH="${OMARCHY_PATH%/}/bin${PATH:+:$PATH}"
fi

```

## Consuming OMARCHY_PATH Across the Codebase

All Omarchy commands read `OMARCHY_PATH` to locate configuration files, plugins, themes, and internal scripts. The codebase consistently uses a shell parameter expansion pattern to provide a safe default when the variable is unset.

In `bin/omarchy-shell`, `bin/omarchy-provision-user`, and `bin/omarchy-version`, you will find this defensive reference pattern:

```bash
omarchy_path=${OMARCHY_PATH:-/usr/share/omarchy}

```

This approach guarantees that even if the bootstrap script is bypassed, components default to the system-wide installation at `/usr/share/omarchy`.

## Practical Usage Examples

### Verifying the Current Runtime Path

Check the active Omarchy installation root from any shell:

```bash
echo "$OMARCHY_PATH"

```

Output:

```text
/usr/share/omarchy

```

### Switching to a Development Checkout

To run Omarchy from a local git repository, export the path to your checkout before launching the shell:

```bash
export OMARCHY_PATH="$HOME/src/omarchy"
omarchy-shell

```

The `env-bootstrap` logic automatically prepends `$OMARCHY_PATH/bin` to your `PATH`, ensuring the checkout's binaries are used.

### Accessing Resources in Shell Scripts

When writing scripts that depend on Omarchy internals, source the bootstrap file and reference files relative to the variable:

```bash
#!/usr/bin/env bash
source "/etc/profile.d/omarchy.sh"

config_file="${OMARCHY_PATH}/config/omarchy/shell.json"
jq '.' "$config_file"

```

### Reading the Path in QML Components

Quickshell-based UIs can access the runtime path through environment introspection:

```qml
// In a QML fixture
readonly property string rootPath: Quickshell.env("OMARCHY_PATH")

```

## Summary

- **`OMARCHY_PATH`** is defined centrally in `default/bash/env-bootstrap` and exported to all shell sessions.
- The variable defaults to `/usr/share/omarchy` unless overridden by [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf).
- **Development checkouts** trigger automatic `PATH` prepending when `OMARCHY_PATH` differs from the system default.
- All Omarchy utilities consume this variable using the `${OMARCHY_PATH:-/usr/share/omarchy}` pattern to locate resources reliably.
- The mechanism supports both system-wide installations and development workflows without code changes.

## Frequently Asked Questions

### What happens if OMARCHY_PATH is not set?

If `OMARCHY_PATH` is undefined, Omarchy binaries fall back to `/usr/share/omarchy` using shell parameter expansion (`${OMARCHY_PATH:-/usr/share/omarchy}`). This ensures the system package installation remains functional even if the bootstrap script is not sourced.

### How do I use a development checkout of Omarchy?

Create or edit [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) to set `OMARCHY_PATH` to your git checkout directory, or export the variable manually in your shell. When the path differs from `/usr/share/omarchy`, the `env-bootstrap` script automatically prepends `$OMARCHY_PATH/bin` to your `PATH`, allowing you to test local changes immediately.

### Where is OMARCHY_PATH defined for system-wide sessions?

The definition originates in `default/bash/env-bootstrap` within the repository. This script is sourced by system-wide configuration files such as [`/etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main//etc/profile.d/omarchy.sh), making the variable available to all login shells, user `~/.bashrc` configurations, and uwsm sessions.

### Can OMARCHY_PATH be used in QML/Quickshell components?

Yes. Quickshell plugins can read the environment variable using `Quickshell.env("OMARCHY_PATH")`, allowing QML components to resolve absolute paths to themes, configuration files, and internal resources relative to the Omarchy installation root.