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

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:

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:

[[ -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:

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:

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:

[[ $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:

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

Run commands against your checkout:

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:

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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}