Getting Started with zload

zload is an ultra-fast, zero-friction plugin manager and loader for Zsh. It delivers < 0.5 ms warm interactive startup overhead by byte-compiling static plugins into a consolidated memory-mapped wordcode bundle (.zwc), automatically arranging safe canonical ordering, and eliminating subprocess forks.

Self-Bootstrapping Installation

Add the following 4 lines to the very top of your ~/.zshrc. When you clone your dotfiles onto a brand new machine, zload automatically clones itself on the very first terminal launch:

### zload ###
if [ ! -d "${HOME}/.zload" ]; then
  git clone --depth 1 https://github.com/casonadams/zload.git "${HOME}/.zload"
fi
source "${HOME}/.zload/zload.zsh"

Why zload is Fast: The Architecture

Traditional Zsh managers (like Oh-My-Zsh and Antigen) suffer from two major performance bottlenecks:

1. Subprocess Forks: Calling git, sed, grep, uname, or $(...) subshells costs 2–5 ms per fork on macOS. zload executes warm interactive startup using 100% pure Zsh builtins—zero forks spawned.
2. Disk I/O and Parsing: Sourcing 20 separate .zsh scripts requires 20 individual disk reads and AST syntax tokenizations. zload merges plugins into a single script (bundle.zsh) and byte-compiles it via zcompile -R into a binary wordcode image (bundle.zsh.zwc). Zsh memory-maps this binary image directly in 0.4 ms.

Flexible Declaration Syntaxes

zload is extraordinarily flexible with how you provide your plugin declarations. You can use whichever style matches your personal preference or editor workflow.

1. Native Array Syntax (Recommended)

Storing plugins in a native Zsh array is the cleanest and most idiomatic format. It provides distinct syntax highlighting in your editor, native ~ expansion, and allows commenting out lines with standard #:

plugins=(
  casonadams/zline
  romkatv/powerlevel10k
  omz:lib/theme-and-appearance.zsh
  omz:lib/key-bindings.zsh
  omz:lib/completion.zsh
  casonadams/fzf.zsh
  casonadams/walh-shell
  lukechilds/zsh-nvm --on nvm,node,npm
  zsh-users/zsh-syntax-highlighting --defer
  zsh-users/zsh-autosuggestions
)

zload "${plugins[@]}"

2. Multiline String Syntax

If you prefer a single quoted block with linebreaks:

zload "
  romkatv/powerlevel10k
  omz:lib/theme-and-appearance.zsh
  casonadams/walh-shell
  lukechilds/zsh-nvm --on nvm,node,npm
  zsh-users/zsh-syntax-highlighting --defer
  zsh-users/zsh-autosuggestions
"

3. Line-by-Line Invocations

zload romkatv/powerlevel10k
zload omz:git
zload zsh-users/zsh-syntax-highlighting --defer
zload zsh-users/zsh-autosuggestions

Supported Source Formats

Lazy Loading Primitives

zload provides four distinct lazy-loading modifiers so your shell opens instantly:

1. Command Proxy Stubs (--on)

Heavy runtime tools (like nvm, pyenv, tfswitch) often take 50–150ms to initialize. With --on, zload defines lightweight proxy functions. Startup cost is 0.02 ms; the real tool loads only when invoked:

zload lukechilds/zsh-nvm --on nvm,node,npm
zload ptavares/zsh-tfswitch --on tfswitch,terraform

2. Directory-Triggered Lazy Loading (--on-dir)

Plugins needed only inside certain projects (e.g. Git repositories, Node packages, Cargo workspaces) stay idle until you navigate into a matching directory:

zload "davidde/git-time-metric" --on-dir ".git"
zload "wbinglee/zsh-wakatime" --on-dir "package.json"

3. Post-Prompt Idle Deferral (--defer)

Visual plugins (like syntax highlighting) are scheduled via precmd immediately after the first prompt appears on screen:

zload zsh-users/zsh-syntax-highlighting --defer

4. Post-Install Build Hooks (--build)

Runs compilation or install scripts (like fzf binary installation) after cloning. Zero runtime overhead during shell startup:

zload "junegunn/fzf" --build "./install --bin" --bin "bin"

Smart PATH & Completion Management

Native Array `$PATH` Management (zload path)

Replaces fragile export PATH=... lines with deduplicating path helpers that auto-expand ~ and filter out dead directories:

user_paths=(
  ~/.opencode/bin
  ~/.cargo/bin
  ~/.local/bin
  /opt/homebrew/bin
  /opt/homebrew/sbin
  /usr/local/bin
)

zload path "${user_paths[@]}"

Automatic `~/.zfunc` Discovery

If ~/.zfunc exists on your system (standard directory for uv, rustup, pipx completions), zload automatically detects it and links it into $fpath and bytecode bundles with zero lines in your .zshrc.

Automatic Lazy <Tab> Compinit & Menu Selection

zload automatically arms lazy compinit out of the box whenever plugins are declared. Early compdef calls from plugins are buffered safely until your first <Tab> press. To opt out, set export ZLOAD_NO_COMPINIT=1.

To enable highlighted interactive menu completion navigation, add omz:lib/completion.zsh to your plugin declarations, or set native styles in ~/.zshrc:

# Native highlighted menu selection
zmodload -i zsh/complist
zstyle ':completion:*' menu select
zstyle ':completion:*' list-colors "${(s.:.)LS_COLORS}"

CLI Commands Reference

Fast Prompts & Themes

To complement zload's sub-millisecond shell startup, pairing it with a high-performance prompt engine is recommended:

• zline: Fast, modern pure-Zsh prompt engine. Renders in < 0.7 ms with zero subshell forks and declarative configuration. Recommended default prompt for zload: load via zload casonadams/zline.
• Powerlevel10k: Fast and responsive prompt. Load via zload romkatv/powerlevel10k. Because zload produces zero console output and zero subprocess forks during warm startup, it works seamlessly with Powerlevel10k's Instant Prompt.
• Starship: Cross-shell prompt. Cache its initialization script with zero-subprocess eval caching: zload eval starship "starship init zsh".