# How the OMARCHY_PATH Environment Variable Is Managed in Omarchy

> Learn how the OMARCHY_PATH environment variable is initialized, its default location, and how to override it in Omarchy for custom installations.

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

---

**The `OMARCHY_PATH` environment variable is initialized during shell login by the bootstrap script at `default/bash/env-bootstrap`, defaults to `/usr/share/omarchy`, and can be overridden via the admin-controlled [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) file to specify custom installation roots.**

The `OMARCHY_PATH` environment variable serves as the single source of truth for locating Omarchy resources on your system. According to the basecamp/omarchy source code, this variable determines where the shell discovers configuration files, Lua modules, and executable binaries. It is exported during the login process and consumed by both interactive shells and systemd user services.

## Shell Initialization and Bootstrap Process

When a user logs in, the system sources [`/etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main//etc/profile.d/omarchy.sh) to initialize the Omarchy environment. This script acts as the universal entry point for all login shells on the system.

### System-Wide Entry Point

The file [`etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main/etc/profile.d/omarchy.sh) contains a single directive that delegates initialization to the package's internal bootstrap logic:

```bash
. /usr/share/omarchy/default/bash/env-bootstrap

```

This minimal approach keeps the system's `profile.d` directory clean while ensuring the complex initialization logic lives within the version-controlled Omarchy repository (see [`etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main/etc/profile.d/omarchy.sh)).

### Bootstrap Logic and Default Assignment

The `default/bash/env-bootstrap` script implements conditional logic to define `OMARCHY_PATH`. It checks for administrative overrides before falling back to the packaged installation directory:

```bash
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 block uses **parameter expansion** (`${OMARCHY_PATH:=...}`) with the no-op colon command to assign the default value only if the variable is unset. Administrators can therefore pre-define `OMARCHY_PATH` in [`omarchy.conf`](https://github.com/basecamp/omarchy/blob/main/omarchy.conf) to override the standard `/usr/share/omarchy` location used for packaged binaries and resources.

## Development Mode and PATH Management

Omarchy supports a **dev-link mode** that allows developers to shadow the packaged installation with a local source checkout. When `OMARCHY_PATH` points to any location other than `/usr/share/omarchy`, the bootstrap script modifies the executable search path to prioritize local builds.

### Dev-Link PATH Prepending

The bootstrap script detects non-standard installation paths and prepends the checkout's `bin` directory to `$PATH`:

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

```

This logic ensures that locally compiled commands in `${OMARCHY_PATH}/bin` take precedence over system-installed versions. The **case statement** prevents duplicate entries if the directory already exists in the path string.

### User-Level Tool Integration

Beyond development workflows, the bootstrap script appends user-installed shim directories to support tool managers like `mise`. It adds `$HOME/.local/share/mise/shims` and `$HOME/.local/bin` while maintaining system binaries first in the search order. This configuration ensures non-interactive sessions can locate user-managed development tools without interfering with core system utilities.

## Systemd Service Integration

Systemd user services that depend on Omarchy resources use **conditional environment checks** to ensure proper initialization. Services declare `ConditionEnvironment=OMARCHY_PATH` in their unit files to guarantee they only start when the variable is available in the systemd user session.

For example, the `omarchy-sleep-lock.service` unit includes this directive to prevent startup failures when the environment is not properly propagated. The systemd user manager inherits the environment exported during the login shell initialization, ensuring file paths referencing `$OMARCHY_PATH` resolve correctly within the service context (see `default/systemd/user/omarchy-sleep-lock.service`).

## Practical Usage Examples

Inspect the current value in your interactive shell:

```bash
echo "$OMARCHY_PATH"

```

Temporarily override the path to test a local checkout without modifying system files:

```bash
OMARCHY_PATH=/home/user/omarchy-dev ./bin/omarchy-shell -q

```

Load Omarchy's Lua bootstrap dynamically using the environment variable:

```bash
lua -e 'dofile(os.getenv("OMARCHY_PATH").."/default/hypr/bootstrap.lua")'

```

## Summary

- **[`/etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main//etc/profile.d/omarchy.sh)** sources the bootstrap script during login shell initialization.
- **`default/bash/env-bootstrap`** defines `OMARCHY_PATH`, checking [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) for admin overrides before defaulting to `/usr/share/omarchy`.
- **Admin-controlled configuration** via [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) allows system-wide customization of the installation root without modifying package files.
- **Dev-link mode** activates when `OMARCHY_PATH` differs from the default, prepending `${OMARCHY_PATH}/bin` to `$PATH` to shadow packaged binaries with local builds.
- **Systemd integration** uses `ConditionEnvironment=OMARCHY_PATH` to ensure services start only when the variable is available in the user session.

## Frequently Asked Questions

### How can I permanently change the OMARCHY_PATH on my system?

Create or edit [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) as an administrator and set the `OMARCHY_PATH` variable to your desired installation directory. The bootstrap script sources this file before applying the default value, ensuring your custom path persists across login sessions without modifying the core package files.

### What happens when OMARCHY_PATH points to a development checkout?

When `OMARCHY_PATH` is set to a location other than `/usr/share/omarchy`, the bootstrap script enters dev-link mode and automatically prepends `${OMARCHY_PATH}/bin` to your shell's `$PATH`. This ensures that locally compiled binaries in your checkout take precedence over system-installed versions, allowing you to test changes without affecting the global system installation.

### Why do systemd units use ConditionEnvironment with OMARCHY_PATH?

Systemd user services like `omarchy-sleep-lock.service` declare `ConditionEnvironment=OMARCHY_PATH` to prevent startup failures when the environment is incomplete. This directive ensures the service only activates after the login shell has successfully exported the variable, guaranteeing that configuration files and binaries referenced via `$OMARCHY_PATH` exist and are accessible when the service starts.

### Where is OMARCHY_PATH set if I don't have an /etc/omarchy.conf file?

Without an admin configuration file, the `default/bash/env-bootstrap` script sets `OMARCHY_PATH` to `/usr/share/omarchy` during the login process. This default corresponds to the standard installation prefix where package managers place Omarchy's shared resources, making the system functional immediately after package installation without additional configuration.