zi: a Zsh plugin manager that defers the work

The Z-Shell plugin manager, renamed twice

Zi is a high-performance plugin manager and toolkit for Zsh, and the README is clear that it is the current name of a project with history: it is the Z-Shell ecosystem's plugin manager, formerly known as zplugin and zinit.

That history matters for anyone arriving with an existing configuration. A .zshrc written for zinit uses syntax that Zi does not necessarily accept, and the ice modifier syntax is the part of the surface that has to be learned. The README's own quick start uses the current syntax, and the wiki is where the details live, including the page on ice modifiers and the ecosystem catalogue of plugins and annexes.

The audience is a Zsh user who wants plugins, snippets, completions, release artefacts and command line tools to be handled by one tool, rather than by a mix of a plugin manager, a separate tool installer and a directory of downloaded completions that nobody remembers updating.

The requirements are modest and stated plainly: use Zsh with Git available on PATH. The quick-start installer also uses curl and a POSIX shell, and the README warns that plugins and tools you install may have their own dependencies, which is the usual caveat and the usual source of trouble.

The repository layout supports that scope: zi.zsh is the entry script, lib/ holds the implementation, docs/ the documentation, contracts/ the setup integration contract, scripts/ the automation, tests/ the test suite, benchmarks/ the benchmark directory, and zsh-lint.json the lint configuration.

Turbo mode and the cost of shell startup

The first feature listed is responsive startup, described as deferring plugin loading until after the first prompt with Turbo mode.

This is the design decision that distinguishes Zi from the plugin managers it grew out of, and it is worth understanding what it actually changes. A conventional plugin manager sources a plugin's file during startup, which means the plugin's initialisation code runs before the first prompt. With a large plugin set, that initialisation is the dominant cost of opening a shell, and it is paid every single time, including on the terminal where you only wanted to run one command.

With deferred loading, the shell comes up first and the plugin work happens afterwards. The practical effect for an interactive user is a prompt that appears immediately, with plugins arriving a moment later. The effect for a script is different again, since a non-interactive shell may never need the plugins at all.

The other side of that trade-off is that the plugin is not fully available at the moment the prompt appears, which matters for anything that runs during startup and expects a plugin's function to exist. That is why the documentation devotes a page to ice modifiers and to how dependencies load, and why the configuration guide is separate from the command reference.

The repository also carries benchmarks/ as a directory and a Zsh workflow for syntax and focused regression checks, which tells you the project measures this rather than asserting it.

Sources, snippets and ice modifiers

The feature list describes flexible sources that can load plugins, scripts, completions and release artifacts, and control over loading through ice modifiers that configure downloads, builds and updates.

The quick start shows three forms of the command:

# ~/.zshrc
zi snippet OMZ::plugins/git/git.plugin.zsh
zi light zsh-users/zsh-autosuggestions
zi light z-shell/F-Sy-H

A snippet loads a standalone script, here a single plugin file taken from the Oh My Zsh distribution. A light load takes a plugin from a GitHub repository, and the two examples are zsh-autosuggestions and F-Sy-H, which is fast syntax highlighting. The first load downloads any missing repositories or snippets.

The difference between snippet, light and the other load modes is the depth of loading, and light is the lightest because it skips the reporting machinery that a full load provides. That is the mode to reach for when you want a plugin present without paying for its diagnostics.

Ice modifiers are the configuration layer, and they attach to a load command as modifiers. Where a conventional manager would have a configuration file with a block per plugin, Zi expresses per-plugin settings inline, next to the plugin itself, which keeps the declaration and the configuration together. The documentation splits the topic into a page on ice modifiers and a separate configuration guide for the paths and behaviour that apply globally.

After changing your configuration, the README tells you to reload the shell:

exec zsh -il

and to run zi -h to explore the available commands.

Installing means running a remote script

The quick start has three steps, and the first one is the installation:

sh -c "$(curl -fsSL get.zshell.dev)" --

The README describes what this does. The official installer installs Zi with the default loader profile and adds one short managed source entry to your .zshrc, pointing at the canonical installation page on the wiki.

The important sentence is the warning immediately after it, marked IMPORTANT in the README. It asks you to review the installer source and its published SHA-256 checksum before running a remote installation script.

That request is well placed. The command as written pipes a script from a network endpoint straight into a shell, so the code that decides what lands in your .zshrc is fetched at the moment you run it, over whatever path your network provides, and the two arguments to the sh -c invocation are how you would pass options to it. The README links both the installer source and a checksum file, so the verification path exists; it just is not automatic.

For anyone who would rather not pipe a remote script into a shell, the installation guide covers alternate installers, manual setup, completions and post-install steps. The requirements for the quick path are Zsh with Git on PATH, plus curl and a POSIX shell.

A practical note for anyone who already has Zsh configured: the installer adds an entry to your .zshrc, and the README is explicit that your own plugin commands belong after that managed source entry, which is where the quick start places them.

Tools without root, annexes, and the setup contract

Two capabilities go beyond the usual plugin manager remit.

Tool management means installing command line tools without root access. The usual pattern for that is a package manager that writes into a user-owned prefix, which avoids sudo and avoids fighting the system package database. Folding it into the plugin manager means one place declares both the plugins that extend the shell and the binaries the shell calls, and one update command covers both.

Extensions are added through Zi annexes, and the ecosystem catalogue on the wiki is where plugins and annexes are listed. The catalogue is the closest thing the project has to an app store, and it is also the place to look when you want to know what is supported rather than what is theoretically possible.

The third piece is the setup integration contract, hosted in the z-shell/src repository. The README points automated installers and terminal interfaces at it, and describes it as covering plan and apply phases, results and event handling. That is a meaningful thing for a plugin manager to specify. A shell manager that mutates the user's configuration is not a good citizen in an unattended context, so a contract that separates planning from applying, and defines what results and events look like, lets another tool drive it without guessing. The same repository also hosts the security policy, the contribution guide and the changelogs, which splits the operational surface across two repositories.

For a project of this kind, the split is defensible: the manager and the organisational infrastructure change for different reasons and at different rates.

Branches, releases and the MIT licence

The licence is MIT, with the LICENSE file at the top of the tree and the README pointing at it.

The release record is active. The recent releases are v2.2.3 on 2026-10-08, v2.2.2 on 2026-10-06 and v2.2.1 on 2026-09-20, and the repository is not archived with the last push on 2026-10-19. Two patch releases in three days is the cadence of a project that ships often.

The branch model is described in the contributing section. Development work targets the next branch, while main contains production releases, and the contribution guide covers the branch model and the release process. There is also a Zsh workflow for the syntax and focused regression checks used to verify a checkout, plus a zsh-lint.json, so the project lints its own shell code.

Support and reporting routes are the conventional GitHub ones. Usage questions go to the Z-Shell Discussions area, reproducible defects go through the Zi issues tracker, and the wider Z-Shell organisation is linked for the ecosystem at large. Vulnerabilities have their own path: the security policy asks for private reporting, and the README is explicit that a vulnerability should not be disclosed in a public issue before a fix is available. That is the right instruction for a tool that runs arbitrary third-party plugin code on a user's machine, and it is worth reading before deciding how much to trust a plugin you found in a catalogue.

One thing the README does not document is any rollback or version pinning story beyond the tag list. If you want to be able to return to a known-good configuration after a plugin update, you will want to take a copy of your .zshrc and of the plugin directory yourself, because the documentation does not offer you a way to do it.

Editorial conclusion

zi suits a Zsh user whose shell startup has become slow, or who wants to install plugins, snippets and command line tools from one place with a single consistent syntax. It does not suit somebody who wants to keep their existing zinit configuration untouched, since the project has been renamed twice and the ice modifier syntax is its own, and it does not suit a user who wants to avoid running a remote installation script. Before adopting, review the installer source and its published SHA-256 checksum as the README asks, then measure your own shell startup before and after with the deferred loading turned on, since that is the claim the project is making.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. z-shell/zi on GitHub