# How to Manage OMARCHY_PATH in Omarchy Development: Complete Environment Setup Guide

> Master OMARCHY_PATH in Omarchy development. This guide details environment setup and resource management for the omacom/omarchy repository. Learn to configure OMARCHY_PATH effectively.

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

---

**OMARCHY_PATH is the environment variable that serves as the single source of truth for locating Omarchy resources, falling back to `/usr/share/omarchy` when unset.**

In the `omacom/omarchy` ecosystem, every binary, script, and service relies on **OMARCHY_PATH** to locate QML files, default configurations, and helper scripts. Whether you are deploying the desktop environment on production systems or developing new features in a local checkout, properly managing this variable ensures components resolve resources correctly.

## Understanding OMARCHY_PATH Defaults

The codebase treats `OMARCHY_PATH` as a mandatory environment variable with a safe system-wide default. When the variable is unset, components fall back to `/usr/share/omarchy`.

In `bin/omarchy-version`, the fallback logic appears as:

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

```

This pattern repeats across entry points, ensuring that system installations work immediately after package installation without requiring manual configuration.

## Component-Specific Usage Patterns

Different Omarchy tools validate and consume `OMARCHY_PATH` according to their specific requirements.

### Shell Validation (bin/omarchy-shell)

The shell entry point performs strict validation before launching the QML interface. It checks that the variable is set and that the expected configuration files exist:

```bash
[[ -n ${OMARCHY_PATH:-} ]] || fail "OMARCHY_PATH is not set"
[[ -f $OMARCHY_PATH/shell/shell.qml ]] || fail "omarchy-shell config not found"

```

This prevents the shell from launching with missing resources.

### User Environment Provisioning (bin/omarchy-provision-user)

This script establishes the development environment by exporting `OMARCHY_PATH` and prepending the repository's `bin` directory to `PATH`:

```bash
export OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"
export PATH="$OMARCHY_PATH/bin:$PATH"

```

It also sources skill scripts relative to this path, making it critical for user session initialization.

### Configuration Refresh (bin/omarchy-refresh-config)

When refreshing user configurations, the script resolves default files against `OMARCHY_PATH`:

```bash
default_config_file="$OMARCHY_PATH/config/$config_file"

```

This allows the command to copy shipped defaults from the repository into `~/.config`.

### Development Updates (bin/omarchy-update-dev)

Development-specific tooling enforces that `OMARCHY_PATH` points to a git repository rather than a system installation:

```bash
[[ $OMARCHY_PATH != "/usr/share/omarchy" ]] || exit 0

```

This safety check prevents accidental modifications to system-wide installations during development workflows.

## Configuring OMARCHY_PATH for Development

For active development, you must override the default system path to point at your local git checkout. This allows immediate testing of changes without reinstallation.

Export the variable and update your `PATH`:

```bash
export OMARCHY_PATH="$HOME/dev/omarchy"
export PATH="$OMARCHY_PATH/bin:$PATH"

```

Run commands against your checkout:

```bash
OMARCHY_PATH="$HOME/dev/omarchy" omarchy-refresh-config hypr/hyprland.lua

```

The test suite demonstrates this pattern by overriding `OMARCHY_PATH` to temporary directories, as seen in [`test/shell.d/xps13-sidecar-amps-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/xps13-sidecar-amps-test.sh):

```bash
OMARCHY_PATH="$ROOT" omarchy-migrate --pending

```

## Common Pitfalls and Solutions

Several issues arise when `OMARCHY_PATH` is misconfigured:

- **Unexported variable in new shells**: If commands report *"OMARCHY_PATH is not set"*, source the export file manually: `source /etc/profile.d/omarchy.sh` or export the variable explicitly.

- **Non-git checkout for development**: `omarchy-update-dev` aborts if `OMARCHY_PATH` points to `/usr/share/omarchy` or a non-git directory. Ensure you develop within a proper clone: `git clone https://github.com/omacom/omarchy.git`.

- **Stale binary resolution**: After changing `OMARCHY_PATH`, run `hash -r` to clear the shell's command cache, or open a fresh terminal to ensure binaries resolve from the new location.

- **Systemd service visibility**: User services require `OMARCHY_PATH` in the systemd environment. Verify with: `systemctl --user show-environment | grep OMARCHY_PATH`

## Summary

- `OMARCHY_PATH` defaults to `/usr/share/omarchy` when unset, as implemented in `bin/omarchy-version`.
- The shell validates the variable strictly before launching, checking for required QML files in `bin/omarchy-shell`.
- Development workflows require pointing `OMARCHY_PATH` at a git checkout and updating `PATH` accordingly.
- `bin/omarchy-update-dev` explicitly prevents operations against system installations to protect production deployments.
- Systemd integration relies on `OMARCHY_PATH` being present in the user environment via `ConditionEnvironment`.

## Frequently Asked Questions

### What happens if OMARCHY_PATH is not set?

Components fall back to `/usr/share/omarchy`, but interactive shells like `omarchy-shell` will fail fast with an explicit error message: *"OMARCHY_PATH is not set"*. Always export the variable before running administrative commands or develop in a shell where the variable is properly sourced from [`/etc/profile.d/omarchy.sh`](https://github.com/omacom/omarchy/blob/main//etc/profile.d/omarchy.sh).

### Can I use a user-owned directory for OMARCHY_PATH?

Yes, for development. Set `OMARCHY_PATH="$HOME/dev/omarchy"` and ensure your `PATH` includes `$OMARCHY_PATH/bin`. However, production deployments typically keep `OMARCHY_PATH` owned by root under `/usr/share/omarchy` for security isolation, as expected by system-level services.

### How do I verify OMARCHY_PATH is correctly detected by systemd?

Run `systemctl --user show-environment | grep OMARCHY_PATH`. The output should display your expected path. If missing, the variable was not imported into the systemd user session, which can break services that depend on Omarchy binaries located at `$OMARCHY_PATH/bin`.

### Why does omarchy-update-dev require a git checkout?

The script contains safeguards: `[[ $OMARCHY_PATH != "/usr/share/omarchy" ]] || exit 0`. This prevents developers from accidentally running migration scripts against the system-wide installation, ensuring modifications only occur within development repositories where version control can track changes.