# How the env-bootstrap System Configures OMARCHY_PATH and PATH in Omarchy

> Discover how the env-bootstrap system in Omarchy configures OMARCHY_PATH and PATH, prioritizing development binaries and managing user tools for efficient environment setup.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-28

---

**The env-bootstrap system centralizes Omarchy's environment configuration by sourcing a single script across all shell contexts, determining `OMARCHY_PATH` from [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) or defaulting to `/usr/share/omarchy`, then restructuring `PATH` to prioritize development binaries when applicable while appending user-level tools and preventing duplicates.**

The env-bootstrap mechanism serves as the single source of truth for runtime environment configuration in the basecamp/omarchy repository. This system ensures consistent variable initialization across login shells, SSH sessions, and graphical environments by centralizing logic in one master script. Understanding how the env-bootstrap system configures both `OMARCHY_PATH` and `PATH` is essential for developers customizing their Omarchy installation or troubleshooting environment issues.

## env-bootstrap System Architecture and Entry Points

The master environment logic resides in `default/bash/env-bootstrap`, which acts as the centralized configuration engine. This script is invoked through multiple wrapper files to ensure coverage across different execution contexts, and its behavior is validated by [`test/shell.d/dev-env-path-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/dev-env-path-test.sh).

The following files source the bootstrap script:

- [`etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main/etc/profile.d/omarchy.sh) – System-wide entry point for login shells, installed to [`/etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main//etc/profile.d/omarchy.sh)
- `/etc/skel/.bashrc` – Interactive shell initialization template
- `default/uwsm/env.d/10-omarchy` – uwsm Hyprland session environment, installed to `/usr/share/uwsm/env.d/10-omarchy`
- `default/bash/envs` – Additional environment sourcing layer

This multi-point sourcing strategy guarantees that whether you access the system via terminal, SSH, or graphical session, the environment remains consistent.

## How OMARCHY_PATH Is Determined

The bootstrap script first establishes the `OMARCHY_PATH` variable, which defines the root directory for Omarchy's resources and binaries. The logic implements a cascading configuration pattern with a secure fallback.

### Configuration File Parsing

When the script executes, it checks for the presence of [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf), a host-administrative configuration file typically written by `omarchy-dev-link`:

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

```

If [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) exists, the script sources it, allowing administrators to override `OMARCHY_PATH` with an active development checkout (e.g., `/home/user/omarchy`). The `${OMARCHY_PATH:=/usr/share/omarchy}` syntax ensures that if the configuration file omits the variable, it defaults to the packaged production path `/usr/share/omarchy`. If the configuration file does not exist at all, the script explicitly sets and exports the default path.

## PATH Modification Strategy

After establishing `OMARCHY_PATH`, the script modifies `PATH` through three distinct stages, each using case-statement pattern matching to prevent duplicate entries. The modifications prioritize system integrity while accommodating development workflows.

### Stage 1: Prepending Omarchy Binaries in Dev-Link Mode

When `OMARCHY_PATH` differs from the default `/usr/share/omarchy` (indicating a development link), the script prepends the custom Omarchy binary directory to ensure development builds take precedence:

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

```

This conditional prepending ensures that development versions of Omarchy tools override system-wide installations only when explicitly configured via [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf).

### Stage 2: Appending Mise Shims

The script unconditionally appends the mise version manager shims directory, which provides user-installed language runtimes:

```bash
case ":$PATH:" in
  *":$HOME/.local/share/mise/shims:"*) ;;
  *) PATH="${PATH:+$PATH:}$HOME/.local/share/mise/shims" ;;
esac

```

By appending rather than prepending, the system preserves the priority of distribution-managed binaries while making user-managed tool versions available.

### Stage 3: Appending User-Local Binaries

Finally, the script appends the user's local binary directory:

```bash
case ":$PATH:" in
  *":$HOME/.local/bin:"*) ;;
  *) PATH="${PATH:+$PATH:}$HOME/.local/bin" ;;
esac

export PATH

```

This placement ensures that user-installed utilities are available but do not override system or Omarchy-specific tools.

### Duplicate Prevention Mechanism

Each modification stage uses the `case ":$PATH:" in *":$target:"*)` pattern to wrap the existing `PATH` with colons, enabling reliable substring matching. This technique prevents the accumulation of duplicate entries across multiple shell initializations, particularly important for long-running sessions or nested shells.

## Complete Execution Flow

The env-bootstrap script executes the following deterministic sequence:

1. **Source configuration**: Checks for and sources [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) if present
2. **Set OMARCHY_PATH**: Defaults to `/usr/share/omarchy` if not set by configuration
3. **Export OMARCHY_PATH**: Makes the variable available to child processes
4. **Conditional PATH prepend**: Adds `${OMARCHY_PATH%/}/bin` to the front only when in development mode
5. **PATH append operations**: Adds mise shims and `~/.local/bin` to the end, skipping duplicates
6. **Export PATH**: Finalizes the environment for all inheriting processes

## Practical Configuration Examples

Inspecting the environment after sourcing reveals the bootstrap behavior in different scenarios.

**Production installation with default paths:**

```bash
$ source /usr/share/omarchy/default/bash/env-bootstrap
$ echo "$OMARCHY_PATH"
/usr/share/omarchy
$ echo "$PATH"
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/user/.local/share/mise/shims:/home/user/.local/bin

```

**Development link configuration:**

```bash

# After configuring /etc/omarchy.conf to point to /home/dev/omarchy

$ source /usr/share/omarchy/default/bash/env-bootstrap
$ echo "$OMARCHY_PATH"
/home/dev/omarchy
$ echo "$PATH"
/home/dev/omarchy/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/dev/.local/share/mise/shims:/home/dev/.local/bin

```

The development example demonstrates how `/home/dev/omarchy/bin` appears at the beginning of `PATH`, while the mise shims and local bin directories maintain their positions at the end.

**Duplicate prevention verification:**

```bash
$ export PATH="/usr/bin:/home/user/.local/bin"
$ source /usr/share/omarchy/default/bash/env-bootstrap
$ echo "$PATH"
/usr/bin:/home/user/.local/bin:/home/user/.local/share/mise/shims

```

Note that `~/.local/bin` appears only once, and the mise shims are appended without duplication.

## Summary

- The **env-bootstrap system** centralizes environment configuration in `default/bash/env-bootstrap`, sourced by multiple shell entry points including [`etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main/etc/profile.d/omarchy.sh) and the uwsm environment.
- **OMARCHY_PATH** defaults to `/usr/share/omarchy` but can be overridden via [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) for development workflows.
- **PATH modifications** occur in three stages: conditional prepending of Omarchy binaries (development mode only), followed by appending mise shims and user-local binaries.
- **Duplicate prevention** uses colon-wrapped pattern matching to ensure idempotent environment configuration across multiple shell initializations.
- The system maintains **hierarchical tool priority**: development builds override system packages, while user tools supplement rather than replace system utilities.

## Frequently Asked Questions

### How do I switch to a development version of Omarchy using env-bootstrap?

Create or modify [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) to set `OMARCHY_PATH` to your local checkout directory (e.g., `/home/user/omarchy`). When you next source `default/bash/env-bootstrap` or start a new shell, the script will detect the non-default path, prepend your checkout's `bin` directory to `PATH`, and export the updated `OMARCHY_PATH` variable.

### Why does the env-bootstrap script append rather than prepend user directories to PATH?

The script appends `$HOME/.local/share/mise/shims` and `$HOME/.local/bin` to maintain security and system integrity. This ordering ensures that distribution-managed binaries in `/usr/bin` and Omarchy's own tools take precedence over user-installed utilities, reducing the risk of command shadowing by untrusted or experimental software.

### What prevents duplicate PATH entries when sourcing env-bootstrap multiple times?

The script uses case-statement pattern matching with colon-wrapped PATH strings (`case ":$PATH:" in *":$target:"*)`). This technique detects existing entries regardless of their position in the colon-separated list, allowing the script to skip appending or prepending if the directory is already present, making the configuration idempotent across nested shells or repeated sourcing.

### Where should I look to verify that env-bootstrap is running in my shell session?

Check the value of `OMARCHY_PATH` using `echo $OMARCHY_PATH`. If it returns `/usr/share/omarchy` or your configured development path, the bootstrap has executed. For debugging, you can also examine the first few entries of your `PATH` variable to verify that development binaries appear at the front (if applicable) and that mise shims appear at the end without duplication.