# What Is the Purpose of `default/bash/env-bootstrap` in Omarchy? > Discover how Omarchy's default/bash/env-bootstrap script initializes your environment. It creates a consistent PATH for reliable tooling across shells. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-27 --- **The `default/bash/env-bootstrap` script serves as the central environment initializer for Omarchy, resolving the active `OMARCHY_PATH` and constructing a deterministic, deduplicated `PATH` variable that ensures consistent tooling availability across Bash, Zsh, and POSIX-compatible shells.** The `default/bash/env-bootstrap` file in the [Omarchy repository](https://github.com/basecamp/omarchy) (Basecamp's Arch Linux-based desktop environment) functions as the single source of truth for shell environment preparation. When a user's session starts via [`/etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main//etc/profile.d/omarchy.sh), the default Bash rc, or the UWSM environment, this script is sourced to establish critical environment variables. This ensures that all Omarchy commands, user binaries, and development tools resolve correctly regardless of how the shell is invoked. ## Core Responsibilities of the Bootstrap Script ### Resolving the Active `OMARCHY_PATH` The bootstrap script's primary duty is determining which Omarchy installation should take precedence. It evaluates whether the system should use the default installation directory at `/usr/share/omarchy` or a linked development checkout, ensuring all subsequent Omarchy commands point to the correct location. According to the test suite in [`test/shell.d/dev-env-path-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/dev-env-path-test.sh)【L54-L66】, this logic handles both standard installations and local development environments where developers may have symlinked alternative versions of the framework. ### Building a Deterministic `PATH` After establishing `OMARCHY_PATH`, the script constructs a clean and deterministic `PATH` variable with strict precedence rules. As implemented in the test validations【L56-L73】, the process: - **Prepends** the active checkout's `bin` directory to ensure Omarchy tools take precedence - **Preserves** unrelated existing entries that existed before the script ran - **Appends** user-level paths such as `~/.local/bin` and mise shims after system paths - **Removes duplicate entries** while maintaining the intended order This approach guarantees that system tools, Omarchy-specific utilities, and user-local installations resolve in the correct priority order without polluting the environment with redundant paths. ## Cross-Shell Compatibility Unlike shell-specific configuration files, `env-bootstrap` is designed to work when sourced by **Bash**, **Zsh**, and other POSIX-compatible shells. The script handles differences in how each shell expands and manipulates the `PATH` variable, as verified by compatibility checks in the test suite【L84-L85】. This universality ensures that users switching between shells or using tools like UWSM (Universal Wayland Session Manager) receive identical environment initialization. ## Integration Points Across the System Rather than duplicating environment logic across multiple files, Omarchy centralizes initialization by having various session entry points source `env-bootstrap` directly: - **[`/etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main//etc/profile.d/omarchy.sh)** – Initializes the environment for login shells - **`default/bashrc`** – Provides the bootstrap for interactive Bash sessions - **`default/uwsm/env.d/10-omarchy`** – Ensures graphical sessions launched via UWSM receive the same environment variables This architecture keeps bootstrapping logic maintained in one location while ensuring consistency whether you access Omarchy through a TTY, terminal emulator, or Wayland session. ## Testing and Validation The logic within `env-bootstrap` 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), which verifies that: 1. Path resolution correctly identifies active checkouts versus default installations 2. Duplicate entries are eliminated without losing critical path ordering 3. User-level directories are appended rather than prepended 4. Cross-shell sourcing produces identical environment states These tests ensure that modifications to the bootstrap script do not regress the environment setup across supported shell environments. ## Practical Usage Examples ### Sourcing the Bootstrap Manually To load the Omarchy environment in a new shell session: ```bash # Load the Omarchy environment source /usr/share/omarchy/default/bash/env-bootstrap # Verify that OMARCHY_PATH points to the active checkout echo "$OMARCHY_PATH" # Inspect the constructed PATH echo "$PATH" ``` ### Automatic Integration in Bash The default installation automatically adds this to `~/.bashrc`: ```bash # ~/.bashrc - Omarchy environment setup [[ -r /usr/share/omarchy/default/bash/env-bootstrap ]] && source /usr/share/omarchy/default/bash/env-bootstrap ``` ### Verification Under Zsh To confirm the bootstrap works with Zsh: ```zsh # .zshrc [[ -r /usr/share/omarchy/default/bash/env-bootstrap ]] && source /usr/share/omarchy/default/bash/env-bootstrap # Verify PATH ordering and deduplication print -l $path ``` ## Summary - **`default/bash/env-bootstrap`** is the single source of truth for Omarchy's shell initialization, sourced by login shells, interactive shells, and graphical sessions. - The script resolves `OMARCHY_PATH` to distinguish between default installations (`/usr/share/omarchy`) and linked development checkouts. - It constructs a deterministic `PATH` with strict precedence: Omarchy binaries first, then system tools, then user directories like `~/.local/bin`. - Duplicate path entries are eliminated while preserving intended ordering, as 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 script is POSIX-compatible and functions correctly when sourced by Bash, Zsh, and other shells. ## Frequently Asked Questions ### How does `env-bootstrap` determine which Omarchy checkout to use? The script evaluates the filesystem to determine whether a linked checkout exists or if it should fall back to the default system installation at `/usr/share/omarchy`. This logic ensures that development environments using symlinked versions of Omarchy take precedence over the system-wide installation, while standard installations transparently use the default path. ### Can I use `env-bootstrap` with Zsh instead of Bash? Yes. The script is designed for cross-shell compatibility and handles the nuances of `PATH` expansion in both Bash and Zsh, as well as other POSIX-compatible shells. The test suite explicitly validates this behavior to ensure consistent initialization regardless of your chosen shell. ### Where should I source `env-bootstrap` in my custom shell configuration? You should source it early in your shell's initialization file (such as `~/.bashrc` or `~/.zshrc`), but the recommended approach is to allow Omarchy's default installation to manage this automatically via [`/etc/profile.d/omarchy.sh`](https://github.com/basecamp/omarchy/blob/main//etc/profile.d/omarchy.sh) or the provided `default/bashrc` templates. If you must source it manually, ensure it runs before any commands that depend on Omarchy-specific binaries. ### How does Omarchy prevent duplicate entries in `PATH`? The bootstrap script implements deduplication logic that removes duplicate path entries while maintaining the intended precedence order. This ensures that if a directory appears multiple times (for example, through repeated sourcing or system-wide defaults), only the first occurrence is retained, keeping the environment clean and reducing command lookup overhead.