How the OMARCHY_PATH Environment Variable Is Managed in Omarchy

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 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 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 contains a single directive that delegates initialization to the package's internal bootstrap logic:

. /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).

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:

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

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:

echo "$OMARCHY_PATH"

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

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

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

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

Summary

• /etc/profile.d/omarchy.sh sources the bootstrap script during login shell initialization.
• default/bash/env-bootstrap defines OMARCHY_PATH, checking /etc/omarchy.conf for admin overrides before defaulting to /usr/share/omarchy.
• Admin-controlled configuration via /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 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.

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