zpmod

⚙️ Automatic Zsh script compilation and source profiling.

zpmod is a binary Zsh module (zmodload) that automates Zsh's native .zwc compilation of sourced scripts.

Later shell startups can reuse compiled scripts without you manually running zcompile after each source update.

It works with or without a plugin manager. Its startup benefit depends on how much time your setup spends parsing scripts.

Quick start

# Use the RESOLVED_MODULE_DIR printed by the installer.
module_path+=("/absolute/path/from/RESOLVED_MODULE_DIR")
zmodload -i zpmod

# After the shell starts, profile sourced scripts
zpmod source-study

How it works

source file -> freshness check -> compile or reuse .zwc -> execute -> source-study report

zpmod keeps Zsh's native .zwc format visible and testable. It automates the freshness check and compilation step, then records source timing for later inspection. A typical report looks like:

⏱️    3 ms    plugin-a.plugin.zsh
⏱️   12 ms    plugin-b.plugin.zsh

Timings vary by machine and shell setup. The report is diagnostic data, not a performance guarantee.

Measured startup modes

The purpose is faster later startups through automatic compilation, with a preparation cost when compilation is needed.

Mode	Median	p95
Plain source	11.564 ms	13.331 ms
zpmod first run	13.378 ms	15.495 ms
zpmod warm	4.082 ms	4.210 ms
Manual .zwc	3.760 ms	3.880 ms

Why use zpmod if the first run is slower?

• Plain source: Zsh parses the uncompiled scripts on every startup.
• zpmod first run: zpmod compiles the scripts during startup, so this run includes extra preparation work.
• zpmod warm: a new shell reuses the .zwc files saved by an earlier run. This includes later terminals, not just the same session.
• Manual .zwc: scripts are compiled before timing starts and loaded without zpmod. Compilation work is excluded from this result.

For this workload, later zpmod startups take about 4.1 ms instead of 11.6 ms with plain sourcing, about 65% less time.

Manual compilation is faster here: 3.8 ms versus 4.1 ms. zpmod adds overhead for automation and source profiling.

If your setup already maintains fresh .zwc files, these results show no additional startup-speed benefit from adding zpmod.

When a source file is newer than its .zwc, zpmod attempts to rebuild it. Missing compiled files also require preparation again.

Compilation avoids reparsing scripts; it does not eliminate the commands they execute during startup.

Scope of the measurement

This v2.0.6 result uses the same synthetic 40-script workload for every mode on one local Linux x86_64 runner.

Each sample starts a fresh zsh -f process with isolated HOME and ZDOTDIR. This is shell-configuration isolation.

The published metadata does not identify a container image. The graph therefore does not establish container-isolated performance.

It does not represent your actual .zshrc, and "first run" does not mean the operating-system filesystem cache was cleared.

See the complete result and environment.

The benchmark methodology describes sampling, isolation controls, and limitations.

Installation

• Traditional system or package install (no zi, no network access during the build): see docs/how-to/system-install.md.
• Install with the CMake helper (zi, user, or system scope): see docs/how-to/install-zpmod-with-cmake.md.
• Install to a custom directory: see docs/how-to/install-custom-dir.md.

--install-zi follows Zi's active path configuration. Without a loaded Zi, it retains a recognized legacy $HOME/.zi home and otherwise uses the absolute XDG data home or $HOME/.local/share. It never migrates data automatically. Because zpmod is a compiled module, rebuild it for each incompatible operating system, architecture, or Zsh version instead of sharing one binary install.

Compatibility

The minimum supported Zsh release is 5.8.1. Prebuilt module compatibility is limited to the platform, architecture, and Zsh combinations exercised by the release and compatibility workflows. See the compatibility reference for the package ABI policy and verification coverage.

Documentation

Full documentation lives under docs/, organized as tutorials, how-to guides, reference, and explanation.

Contributing

See docs/explanation/contributing.md.

License

zpmod contains file-specific licensing. Project-owned module sources marked SPDX-License-Identifier: MIT use the MIT license; files without a more specific notice use the Zsh license. See NOTICE for the package-level scope. The vendored Zsh source remains copyright the Zsh Development Group and retains its own licensing terms.