# How Omarchy's `env-bootstrap` Mechanism Prepares Your Shell Environment

> Learn how Omarchy's env-bootstrap script prepares your shell environment by setting OMARCHY_PATH and creating an ordered PATH before commands run.

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

---

**`env-bootstrap` is a lightweight Bash script in `default/bash/env-bootstrap` that sets `OMARCHY_PATH` and constructs a clean, priority-ordered `PATH` before any Omarchy commands run.**

The **Omarchy `env-bootstrap` mechanism** ensures every shell session starts with predictable environment variables and command resolution. Whether you're running a default installation or an active development checkout, this script guarantees Omarchy resources are found first without polluting your system. Let's examine how it works by analyzing the source code in `basecamp/omarchy`.

## How `OMARCHY_PATH` Gets Resolved

The first job of `env-bootstrap` is determining where Omarchy resources live. The script handles two distinct modes:

- **Default mode**: Resolves to the system installation at `/usr/share/omarchy`
- **Linked mode**: Resolves to your active development checkout directory (e.g., `/home/user/omarchy/quattro/active`)

This dual-mode behavior is verified by tests in [`test/shell.d/dev-env-path-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/dev-env-path-test.sh), which confirm the script reports the correct path in both scenarios.

## PATH Construction Rules

The Omarchy `env-bootstrap` mechanism builds `PATH` through a specific ordering strategy that prioritizes Omarchy commands while preserving user customizations.

### Prepend Omarchy Binaries

The script prepends `$OMARCHY_PATH/bin` so Omarchy commands take precedence over system equivalents:

```bash

# After sourcing, $OMARCHY_PATH/bin appears first

PATH="/home/user/omarchy/quattro/active/bin:/usr/bin:..."

```

### Preserve Existing Entries

Unrelated entries already in your `PATH` are preserved exactly as they were. The script does not strip or reorder non-Omarchy paths.

### Append User-Level Locations

Common user directories are appended for accessibility:

- `~/.local/share/mise/shims`
- `~/.local/bin`

### Eliminate Duplicates

The `linked_duplicate_path` test confirms that duplicate entries are removed to prevent `PATH` bloat when sourcing multiple times.

## Edge Case Handling

The `env-bootstrap` script anticipates several real-world scenarios:

| Scenario | Behavior |
|----------|----------|
| Empty original `PATH` | Builds clean `PATH` from Omarchy `bin` plus user directories |
| zsh shell | `zsh_path` test ensures identical ordering and preservation rules |
| Multiple sourcing | Idempotent execution—safe from multiple startup files |
| Missing source file | Guarded by `[ -r … ]` check before sourcing |

## Safety and Idempotency

The script is deliberately lightweight and guards against errors:

```bash

# Typical sourcing pattern from /etc/profile.d/omarchy.sh

if [[ -r /usr/share/omarchy/default/bash/env-bootstrap ]]; then
  . /usr/share/omarchy/default/bash/env-bootstrap
fi

```

This pattern from [`etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main/etc/profile.d/omarchy.sh) demonstrates how the bootstrap integrates with system-wide shell initialization.

## Key Files in the `env-bootstrap` System

| File | Purpose |
|------|---------|
| `default/bash/env-bootstrap` | Core bootstrap logic implementation |
| [`test/shell.d/dev-env-path-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/dev-env-path-test.sh) | Automated tests documenting expected behavior |
| [`etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main/etc/profile.d/omarchy.sh) | System-wide entry point for sourcing |
| `default/bash/envs` | Interactive shell wrapper ensuring bootstrap loads |
| [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) | Documentation referencing bootstrap location and purpose |

## Verification Examples

After the Omarchy `env-bootstrap` mechanism runs, verify your environment:

```bash

# Check resolution results

echo "OMARCHY_PATH → $OMARCHY_PATH"
echo "PATH → $PATH"

# Example linked checkout output:

# OMARCHY_PATH → /home/user/omarchy/quattro/active

# PATH → /home/user/omarchy/quattro/active/bin:/usr/bin:/home/user/.local/share/mise/shims:/home/user/.local/bin

```

## Summary

- **`default/bash/env-bootstrap`** implements the core Omarchy `env-bootstrap` mechanism
- Resolves `OMARCHY_PATH` for both default (`/usr/share/omarchy`) and linked (active checkout) modes
- Constructs `PATH` by prepending Omarchy binaries, preserving existing entries, appending user directories, and removing duplicates
- Handles edge cases including empty `PATH`, zsh compatibility, and safe re-sourcing
- Integrated via [`etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main/etc/profile.d/omarchy.sh) and tested in [`test/shell.d/dev-env-path-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/dev-env-path-test.sh)

## Frequently Asked Questions

### Where is the `env-bootstrap` script located in Omarchy?

The script lives at `default/bash/env-bootstrap` in the repository. According to the Omarchy source code, this path is referenced from [`etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main/etc/profile.d/omarchy.sh) for system-wide initialization and from `default/bash/envs` for interactive shells. The location is also documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md).

### How does Omarchy handle development checkouts versus default installations?

The `env-bootstrap` mechanism detects linked mode and resolves `OMARCHY_PATH` to your active checkout directory rather than `/usr/share/omarchy`. Tests in [`test/shell.d/dev-env-path-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/dev-env-path-test.sh) verify both resolution behaviors, ensuring developers work against their current code while default installations use system resources.

### Why does my `PATH` have Omarchy directories first after sourcing?

This is intentional design. The script prepends `$OMARCHY_PATH/bin` to ensure Omarchy commands shadow system equivalents of the same name. Your original entries are preserved after this prefix, and user directories like `~/.local/bin` are appended at the end.

### Is `env-bootstrap` safe to run multiple times?

Yes. The script is idempotent and lightweight. The `linked_duplicate_path` test specifically validates that duplicate entries are removed, so repeated sourcing does not inflate your `PATH` with redundant entries.