Getting Started with zload
zload is an ultra-fast, zero-friction plugin manager and loader for Zsh. It delivers ~0.6 ms warm interactive startup overhead (10 plugins, Apple Silicon) 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
Shell startup time is dominated by two costs, and zload is built to eliminate both:
- Subprocess Forks: Calling
git,sed,grep,uname, or$(...)subshells costs milliseconds per fork.zloadexecutes warm interactive startup using 100% pure Zsh builtins—zero forks spawned. - Disk I/O and Parsing: Sourcing 20 separate
.zshscripts requires 20 individual disk reads and AST syntax tokenizations.zloadmerges plugins into a single script (bundle.zsh) and byte-compiles it viazcompile -Rinto a binary wordcode image (bundle.zsh.zwc). Zsh memory-maps this binary image in about 0.35 ms; sourcingzload.zshplus ten plugins measures ~0.6 ms (runzsh benchmark/bench.zshto measure on your machine).
Caching & Invalidation
Every zload <plugins...> call is cold the first time (or when its arguments change) and warm afterwards. A cold call installs missing plugins in parallel, resolves entry scripts, fpath and bin directories, sorts plugins into canonical order, and writes a compiled bundle. A warm call compares its raw arguments with a cached copy and sources the bundle: no subprocesses.
One bundle per zload call
The first call uses bundle.zsh, the second bundle.2.zsh, and so on. You can split plugins across several calls and every call stays warm; changing one call rebuilds only its own bundle. Canonical ordering is applied within a call, so keep plugins that depend on each other in the same call.
Canonical load order
zsh-completions first, then themes and prompts, then everything else in declared order, then zsh-syntax-highlighting, zsh-autosuggestions and zsh-history-substring-search.
What rebuilds the cache
| Event | Effect |
|---|---|
Change the arguments of a zload call | That call's bundle rebuilds on the next shell start. |
zload update, sync, compile | Every bundle is rebuilt in place; the completion dump is cleared when something changed. |
zload clean -f | Removes unreferenced plugins, all bundle.* files and the completion dump. |
zload upgrade | Wipes the cache directory and reloads zload. |
| A bundle is rebuilt with different content | zcompdump* is deleted so new completions are discovered. |
zload eval command string changes, or the tool binary is newer | That eval cache is regenerated. |
Editing a plugin's own scripts takes effect immediately. If a plugin gains a new completion file or bin/ directory, run zload compile so the bundle picks it up. If any plugin in a call fails to install, no bundle is written and the next shell start retries.
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
| Format | Example | Description |
|---|---|---|
| GitHub Repository | user/repo |
Standard GitHub repository, cloned shallowly. |
| Release Tag | user/repo@v1.2.0 |
Checks out a pinned Git release tag. |
| Git Branch | user/repo#develop |
Tracks a specific Git branch. |
| Git Commit | user/repo@3f2a9c1 |
Checks out a pinned commit SHA (7-40 hex characters). |
| Oh-My-Zsh Plugin | omz:git |
Loads plugin from shared OMZ clone; auto-loads lib/git.zsh. |
| Oh-My-Zsh Theme | omz:themes/robbyrussell |
Loads theme file and required color/git dependencies. |
| Oh-My-Zsh Library | omz:lib/key-bindings.zsh |
Sources core OMZ helper libraries directly. |
| Prezto Module | prezto:utility |
Loads Prezto module and autoloads its functions/ directory. |
| Remote Snippet | snippet:https://.../tool.zsh |
Downloads single script via curl without Git clone overhead. |
| Precompiled Binary | user/repo --from gh-r |
Downloads the release asset matching your OS/Arch into PATH; verified against a published .sha256 or --sha256. |
| Arbitrary Git URL | https://gitlab.com/repo.git |
Clones GitLab, Bitbucket, or self-hosted Git repositories. |
| SSH Git URL | git@github.com:user/repo.git |
Clones over SSH; @ref and #ref suffixes work as for other URLs. |
| Local Directory | ~/code/my-local-plugin |
Sources local development plugins from disk (/abs, ~/, ./rel, ../rel). |
Options
Options follow the plugin they apply to. Options that take a value need it as the next argument, e.g. zload user/repo --build "make install".
| Option | Effect |
|---|---|
--on cmd1,cmd2 | Define proxy functions; the plugin is sourced when one of the commands first runs. |
--on-dir pattern | Load when $PWD matches pattern or contains a file named pattern. |
--defer, --idle | Load right after the first prompt is drawn. |
--path dir, --subpath dir | Use a subdirectory of the plugin as its root (monorepos). |
--bin dir | Add dir (relative to the plugin) to $PATH. |
--build cmd, --hook cmd | Run cmd in the clone after install and after updates pull new commits. Failures are reported and retried. |
--from gh-r | Install a GitHub release asset matching your OS and CPU. |
--sha256 hash | Reject a snippet or release asset unless its SHA-256 matches. |
A @ref can be a tag, a branch, or a commit SHA (7-40 hex characters).
zload snippet:https://example.com/tool.zsh --sha256 <sha256-of-the-file>
zload sharkdp/fd --from gh-r
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 effectively zero; 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) load right after the first prompt is drawn, via a one-shot zle -F callback, so they never delay it:
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, executing completion seamlessly on that first press with zero dropped keystrokes. 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
| Command | Description |
|---|---|
zload path [dir...] |
Prepends existing directories to $PATH with ~ expansion and deduplication; with no arguments prints the active $PATH. |
zload fpath [dir...] |
Prepends directories to $fpath with validation and deduplication; with no arguments prints it. |
zload update [--all|--self|-f] |
Updates installed plugins in parallel, re-fetches snippets, reinstalls unpinned release binaries and re-runs build hooks; --all also updates zload; -f discards local modifications. |
zload upgrade [-f] |
Upgrades zload to latest release, recompiles modules, wipes runtime cache, and reloads active shell. Pass -f to force. |
zload clean [-f] |
Lists plugin directories that this session does not reference; -f deletes them and flushes bundle and completion caches. |
zload list |
Lists installed plugins with active Git branch, tag, and commit SHA. |
zload which <plugin> |
Prints the full canonical directory path of an installed plugin. |
zload cd <plugin> |
Changes the current working directory to the plugin's root on disk. |
zload doctor [--fix] |
Runs health diagnostics; --fix automatically compiles missing wordcode. |
zload profile |
Profiles shell startup latency breakdown using microsecond timers. |
zload eval <name> <cmd> |
Caches subshell command output into memory-mapped wordcode (.zwc). |
zload lock [file] |
Exports pinned commit hashes of Git plugins to a reproducible lockfile (release binaries and snippets are not locked). |
zload sync [file] |
Checks out the lockfile commits (fetching on shallow clones), installs declared plugins that are missing, and exits non-zero if any commit cannot be checked out. |
zload compile |
Rebuilds every bundle (one per zload call), core modules, and installed plugin bytecode (.zwc). |
zload compinit [--lazy] |
Initializes or defers the Zsh completion system (defers until first <Tab> with --lazy; armed on expand-or-complete, complete-word, menu-complete and the other widgets compinit rebinds). |
zload help |
Prints a one-screen summary of commands, options and sources. |
Environment Variables
| Variable | Default | Purpose |
|---|---|---|
ZLOAD_HOME | Directory of zload.zsh | zload installation. |
ZLOAD_DATA | ${XDG_DATA_HOME:-~/.local/share}/zload | Plugin and lockfile storage. |
ZLOAD_CACHE | ${XDG_CACHE_HOME:-~/.cache}/zload | Bundles, completion dump, eval caches. |
ZLOAD_PLUGINS | $ZLOAD_DATA/plugins | Cloned plugins. |
ZLOAD_NO_COMPINIT | unset | Set to stop zload from arming lazy compinit. |
GITHUB_TOKEN | unset | Sent to the GitHub API by --from gh-r to avoid anonymous rate limits. |
Troubleshooting
Start with zload doctor; zload doctor --fix creates missing directories and compiles missing wordcode.
| Symptom | Cause and fix |
|---|---|
| A new plugin's completions do not show up | Run zload compile (or zload update) so its completion directory is added. |
zload: failed to install <spec> | The reason from git or curl follows. Fix the spec or network and open a new shell; no bundle was written, so it retries. |
| A build hook failed | Its output is printed and the half-built plugin is removed so it is retried on the next start. |
--from gh-r: no asset matches | No release asset names your OS and CPU architecture. zload does not guess; install the tool another way. |
--from gh-r: rate limit | Export GITHUB_TOKEN. |
checksum mismatch / sha256 mismatch | The download did not match the published checksum or your --sha256. Nothing was installed. |
zload sync: could not check out | The commit is no longer reachable from the remote. Re-run zload lock from a working setup. |
| Tab never triggers lazy compinit | Tab is bound to a widget zload does not hook. Call zload compinit after your bindkey lines. |
| Stale or odd cache state | zload clean -f clears bundles and the completion dump; the next shell rebuilds them. |
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 viazload casonadams/zline. - Powerlevel10k: Fast and responsive prompt. Load via
zload romkatv/powerlevel10k. Becausezloadproduces 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".