Zinit

• Zinit Wiki
• Install
  • Automatic
  • Manual
• Usage
  • Introduction
  • Plugins and snippets
  • Upgrade Zinit and plugins
  • Turbo and lucid
  • Migration
• Frequently Asked Questions
  • Use zi ice svn if a plugin/snippet requires an entire subdirectory
  • Use zi ice as'completion' to directly add single file completion snippets
  • More Examples
• Ice Modifiers
  • Cloning Options
  • Selection of Files (To Source, …)
  • Conditional Loading
  • Plugin Output
  • Completions
  • Command Execution After Cloning, Updating or Loading
  • Sticky-Emulation Of Other Shells
  • Others
  • Order of Execution
• Zinit Commands
  • Help
  • Loading and Unloading
  • Completions
  • Tracking of the Active Session
  • Reports and Statistics
  • Compiling
  • Other
• Updating Zinit and Plugins
• Completions
  • Calling compinit Without Turbo Mode
  • Calling compinit With Turbo Mode
  • Ignoring Compdefs
  • Disabling System-Wide compinit Call (Ubuntu)
• Zinit Module
• Hints and Tips
  • Using ZPFX variable
  • Customizing Paths
  • Non-GitHub (Local) Plugins
  • Extending Git
• Changelog
• Support
• Getting Help and Community

Zinit is a flexible and fast Zshell plugin manager that will allow you to install everything from GitHub and other sites. Its characteristics are:

1. Zinit is currently the only plugin manager that provides Turbo mode, which yields 50-80% faster Zsh startup (i.e., the shell will start up to 5 times faster!). Check out a speed comparison with other popular plugin managers here.

2. The plugin manager gives reports from plugin loadings describing what aliases, functions, bindkeys, Zle widgets, zstyles, completions, variables, PATH and FPATH elements a plugin has set up. This allows one to quickly familiarize oneself with a new plugin and provides rich and easy-to-digest information which might be helpful on various occasions.

3. Supported is the unloading of plugin and ability to list, (un)install and selectively disable, enable plugin's completions.

4. The plugin manager supports loading plugins and libraries from Oh My Zsh or Prezto. However, the implementation isn't framework-specific and doesn't bloat the plugin manager with such code (more on this topic can be found on the Wiki, in the Introduction).

5. The system does not use $FPATH, loading multiple plugins doesn't clutter $FPATH with the same number of entries (e.g. 10, 15 or more). Code is immune to KSH_ARRAYS and other options typically causing compatibility problems.

6. Zinit supports special, dedicated packages that offload the user from providing long and complex commands. See the zinit-packages repository for a growing, complete list of Zinit packages and the Wiki page for an article about the feature.

7. Also, specialized Zinit extensions — called annexes — have the ability to extend the plugin manager with new commands, URL-preprocessors (used by e.g.: zinit-annex-readurl annex), post-install and post-update hooks, and much more. See the zdharma-continuum organization for a growing, complete list of available Zinit extensions and refer to the Wiki article for an introduction on creating your annex.

Zinit Wiki

The information in this README is complemented by the Zinit Wiki. The README is an introductory overview of Zinit, while the Wiki gives complete information with examples. Make sure to read it to get the most out of Zinit.

Install

Automatic

The easiest way to install Zinit is to execute:

bash -c "$(curl --fail --show-error --silent --location https://raw.githubusercontent.com/zdharma-continuum/zinit/HEAD/scripts/install.sh)"

This will install Zinit in ~/.local/share/zinit/zinit.git. .zshrc will be updated with three lines of code that will be added to the bottom. The lines will be sourcing zinit.zsh and setting up completion for command zinit.

After installing and reloading the shell, compile Zinit via:

zinit self-update

Manual

In your .zshrc, add the following snippet

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
[ ! -d $ZINIT_HOME ] && mkdir -p "$(dirname $ZINIT_HOME)"
[ ! -d $ZINIT_HOME/.git ] && git clone https://github.com/zdharma-continuum/zinit.git "$ZINIT_HOME"
source "${ZINIT_HOME}/zinit.zsh"

compinit):

If you source zinit.zsh after compinit, add the following snippet after sourcing zinit.zsh:

autoload -Uz _zinit
(( ${+_comps} )) && _comps[zinit]=_zinit

Reload Zsh to install Zinit:

exec zsh

Various paths can be customized; see section Customizing Paths.

Usage

Introduction

Click here to read the introduction to Zinit. It explains basic usage and some of the more unique features of Zinit, such as the Turbo mode. If you're new to Zinit, we recommend you read it at least once.

Plugins and snippets

Plugins can be loaded using load or light.

zinit load  <repo/plugin> # Load with reporting/investigating.
zinit light <repo/plugin> # Load without reporting/investigating.

If you want to source local or remote files (using direct URL), you can do so with snippet.

zinit snippet <URL>

Such lines should be added to .zshrc. Snippets are cached locally. Use the -f option to download a new version of a snippet or zinit update {URL}. You can also use zinit update --all to update all snippets (and plugins).

Example

# Plugin history-search-multi-word loaded with investigating.
zinit load zdharma-continuum/history-search-multi-word

# Two regular plugins loaded without investigating.
zinit light zsh-users/zsh-autosuggestions
zinit light zdharma-continuum/fast-syntax-highlighting

# Snippet
zinit snippet https://gist.githubusercontent.com/hightemp/5071909/raw/

Prompt(Theme) Example

This is powerlevel10k, pure, starship sample:

# Load powerlevel10k theme
zinit ice depth"1" # git clone depth
zinit light romkatv/powerlevel10k

# Load pure theme
zinit ice pick"async.zsh" src"pure.zsh" # with zsh-async library that's bundled with it.
zinit light sindresorhus/pure

# Load starship theme
# line 1: `starship` binary as command, from github release
# line 2: starship setup at clone(create init.zsh, completion)
# line 3: pull behavior same as clone, source init.zsh
zinit ice as"command" from"gh-r" \
          atclone"./starship init zsh > init.zsh; ./starship completions zsh > _starship" \
          atpull"%atclone" src"init.zsh"
zinit light starship/starship

Upgrade Zinit and plugins

Zinit can be updated to self-update and plugins to update.

# Self update
zinit self-update

# Plugin update
zinit update

# Plugin parallel update
zinit update --parallel

# Increase the number of jobs in a concurrent-set to 40
zinit update --parallel 40

Turbo and lucid

Turbo and lucid are the most used options.

zinit ice wait    # wait is the same as wait"0"
zinit load zdharma-continuum/history-search-multi-word

zinit ice wait"2" # load after 2 seconds
zinit load zdharma-continuum/history-search-multi-word

zinit ice wait    # also be used in `light` and `snippet`
zinit snippet https://gist.githubusercontent.com/hightemp/5071909/raw/

zinit ice wait lucid
zinit load zdharma-continuum/history-search-multi-word

F&A: What is ice?

ice is zinit's options command. The option melts like ice and is used only once. (more: Ice Modifiers)

Migration

zinit snippet <URL>        # Raw Syntax with URL
zinit snippet OMZ::<PATH>  # Shorthand OMZ/ (https://github.com/ohmyzsh/ohmyzsh/raw/master/)
zinit snippet OMZL::<PATH> # Shorthand OMZ/lib/
zinit snippet OMZT::<PATH> # Shorthand OMZ/themes/
zinit snippet OMZP::<PATH> # Shorthand OMZ/plugins/

# Raw Syntax
zi snippet https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/clipboard.zsh
zi snippet https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/termsupport.zsh

# OMZ Shorthand Syntax
zi snippet OMZ::lib/clipboard.zsh
zi snippet OMZ::lib/termsupport.zsh

# OMZL Shorthand Syntax
zi snippet OMZL::clipboard.zsh
zi snippet OMZL::termsupport.zsh

## Oh My Zsh Setting
ZSH_THEME="robbyrussell"

## Zinit Setting
# Must Load OMZ Git library
zi snippet OMZL::git.zsh

# Load Git plugin from OMZ
zi snippet OMZP::git
zi cdclear -q # <- forget completions provided up to this moment

setopt promptsubst

# Load Prompt
zi snippet OMZT::robbyrussell

## Oh My Zsh Setting
ZSH_THEME="alpharized"

## Zinit Setting
# Must Load OMZ Git library
zi snippet OMZL::git.zsh

# Load Git plugin from OMZ
zi snippet OMZP::git
zi cdclear -q # <- forget completions provided up to this moment

setopt promptsubst

# Load Prompt
zi light NicoSantangelo/Alpharized

........:1: command not found: git_prompt_status
........:1: command not found: git_prompt_short_sha

## Oh-My-Zsh Setting
plugins=(
  git
  dotenv
  rake
  rbenv
  ruby
)

## Zinit Setting
zi snippet OMZP::git
zi snippet OMZP::dotenv
zi snippet OMZP::rake
zi snippet OMZP::rbenv
zi snippet OMZP::ruby

zi ice svn
zi snippet OMZP::gitfast

zi ice svn
zi snippet OMZP::osx

zi ice as"completion"
zi snippet OMZP::docker/_docker

zi ice as"completion"
zi snippet OMZP::fd/_fd

zi snippet <URL>        # Raw Syntax with URL
zi snippet PZT::<PATH>  # Shorthand PZT/ (https://github.com/sorin-ionescu/prezto/tree/master/)
zi snippet PZTM::<PATH> # Shorthand PZT/modules/

## Prezto Setting
zstyle ':prezto:load' pmodule 'environment' 'terminal'

## Zinit Setting
# Raw Syntax
zi snippet https://github.com/sorin-ionescu/prezto/blob/master/modules/environment/init.zsh
zi snippet https://github.com/sorin-ionescu/prezto/blob/master/modules/terminal/init.zsh

# PZT Shorthand Syntax
zi snippet PZT::modules/environment
zi snippet PZT::modules/terminal

# PZTM Shorthand Syntax
zi snippet PZTM::environment
zi snippet PZTM::terminal

zi ice svn
zi snippet PZTM::docker

zi ice svn
zi snippet PZTM::git

zi ice svn as"null"
zi snippet PZTM::archive

zi ice \
  atclone"git clone --recursive https://github.com/zsh-users/zsh-completions.git external" \
  blockf \ # use blockf to prevent any unnecessary additions to fpath, as zinit manages fpath
  svn

zi snippet PZTM::completion

# Load ohmyzsh base
zgen oh-my-zsh
zi snippet OMZL::<ALL OF THEM>

# Load ohmyzsh plugins
zgen oh-my-zsh <PATH>
zi snippet OMZ::<PATH>

# Load Prezto
zgen prezto
zi snippet PZTM::<COMMENT's List> # environment terminal editor history directory spectrum utility completion prompt

# Load prezto plugins
zgen prezto <modulename>
zi snippet PZTM::<modulename>

# Load a repo as Prezto plugins
zgen pmodule <reponame> <branch>
zi ice ver"<branch>"
zi load <repo/plugin>

# Set prezto options
zgen prezto <modulename> <option> <value(s)>
zstyle ':prezto:<modulename>:' <option> <values(s)> # Set original prezto style

zgen load <repo> [location] [branch]

zi ice ver"[branch]"
zi load <repo>

zplug <repo/plugin>, tag1:<option1>, tag2:<option2>

zi ice tag1"<option1>" tag2"<option2>"
zi load <repo/plugin>

More Examples

After installing Zinit you can start adding some actions (load some plugins) to ~/.zshrc, at bottom. Some examples:

# Load the pure theme, with zsh-async library that's bundled with it.
zi ice pick"async.zsh" src"pure.zsh"
zi light sindresorhus/pure

# A glance at the new for-syntax – load all of the above
# plugins with a single command. For more information see:
# https://zdharma-continuum.github.io/zinit/wiki/For-Syntax/
zinit for \
    light-mode \
  zsh-users/zsh-autosuggestions \
    light-mode \
  zdharma-continuum/fast-syntax-highlighting \
  zdharma-continuum/history-search-multi-word \
    light-mode \
    pick"async.zsh" \
    src"pure.zsh" \
  sindresorhus/pure

# Binary release in archive, from GitHub-releases page.
# After automatic unpacking it provides program "fzf".
zi ice from"gh-r" as"program"
zi light junegunn/fzf

# One other binary release, it needs renaming from `docker-compose-Linux-x86_64`.
# This is done by ice-mod `mv'{from} -> {to}'. There are multiple packages per
# single version, for OS X, Linux and Windows – so ice-mod `bpick' is used to
# select Linux package – in this case this is actually not needed, Zinit will
# grep operating system name and architecture automatically when there's no `bpick'.
zi ice from"gh-r" as"program" mv"docker* -> docker-compose" bpick"*linux*"
zi load docker/compose

# Vim repository on GitHub – a typical source code that needs compilation – Zinit
# can manage it for you if you like, run `./configure` and other `make`, etc.
# Ice-mod `pick` selects a binary program to add to $PATH. You could also install the
# package under the path $ZPFX, see: https://zdharma-continuum.github.io/zinit/wiki/Compiling-programs
zi ice \
  as"program" \
  atclone"rm -f src/auto/config.cache; ./configure" \
  atpull"%atclone" \
  make \
  pick"src/vim"
zi light vim/vim

# Scripts built at install (there's single default make target, "install",
# and it constructs scripts by `cat'ing a few files). The make'' ice could also be:
# `make"install PREFIX=$ZPFX"`, if "install" wouldn't be the only default target.
zi ice as"program" pick"$ZPFX/bin/git-*" make"PREFIX=$ZPFX"
zi light tj/git-extras

# Handle completions without loading any plugin; see "completions" command.
# This one is to be ran just once, in interactive session.
zi creinstall %HOME/my_completions

# For GNU ls (the binaries can be gls, gdircolors, e.g. on OS X when installing the
# coreutils package from Homebrew; you can also use https://github.com/ogham/exa)
zi ice atclone"dircolors -b LS_COLORS > c.zsh" atpull'%atclone' pick"c.zsh" nocompile'!'
zi light trapd00r/LS_COLORS

You can see an extended explanation of LS_COLORS in the Wiki.

# make'!...' -> run make before atclone & atpull
zi ice as"program" make'!' atclone'./direnv hook zsh > zhook.zsh' atpull'%atclone' src"zhook.zsh"
zi light direnv/direnv

You can see an extended explanation of direnv in the Wiki.

If you're interested in more examples, then check out the zinit-configs repository, where users have uploaded their ~/.zshrc and Zinit configurations. Feel free to submit your ~/.zshrc there if it contains Zinit commands.

You can also check out the Gallery of Zinit Invocations for some additional examples.

Also, two articles on the Wiki present an example setup here and here.

How to Use

Ice Modifiers

Following ice modifiers are to be passed to zinit ice ... to obtain described effects. The word ice means something that's added (like ice to a drink) – and in Zinit it means adding modifier to a next zinit command, and also something that's temporary because it melts – and this means that the modification will last only for a single next zinit command.

Some Ice-modifiers are highlighted and clicking on them will take you to the appropriate Wiki page for an extended explanation.

You may safely assume a given ice works with both plugins and snippets unless explicitly stated otherwise.

Cloning Options

Selection of Files (To Source, …)

Conditional Loading

Plugin Output

Completions

Command Execution After Cloning, Updating or Loading

Sticky-Emulation Of Other Shells

Others

Order of Execution

Order of execution of related Ice-mods: atinit -> atpull! -> make'!!' -> mv -> cp -> make! -> atclone/atpull -> make -> (plugin script loading) -> src -> multisrc -> atload.

Zinit Commands

Following commands are passed to zinit ... to obtain described effects.

Help

Loading and Unloading

Completions

Tracking of the Active Session

Reports and Statistics

Compiling

compile

List plugins that are compiled.

zinit [options] compile PLUGIN

compiled

List plugins that are compiled.

zinit compiled

uncompile

List plugins that are compiled.

zinit [options] uncompile PLUGIN

Other

Updating Zinit and Plugins

To update Zinit issue zinit self-update in the command line.

To update all plugins and snippets, issue zinit update. If you wish to update only a single plugin/snippet instead issue zinit update NAME_OF_PLUGIN. A list of commits will be shown:

Some plugins require performing an action each time they're updated. One way you can do this is by using the atpull ice modifier. For example, writing zinit ice atpull'./configure' before loading a plugin will execute ./configure after a successful update. Refer to Ice Modifiers for more information.

The ice modifiers for any plugin or snippet are stored in their directory in a ._zinit subdirectory, hence the plugin doesn't have to be loaded to be correctly updated. There's one other file created there, .zinit_lstupd – it holds the log of the new commits pulled-in in the last update.

Completions

Calling compinit Without Turbo Mode

With no Turbo mode in use, compinit can be called normally, i.e.: as autoload compinit; compinit. This should be done after loading of all plugins and before possibly calling zinit cdreplay.

The cdreplay subcommand is provided to re-play all catched compdef calls. The compdef calls are used to define a completion for a command. For example, compdef _git git defines that the git command should be completed by a _git function.

The compdef function is provided by compinit call. As it should be called later, after loading all of the plugins, Zinit provides its own compdef function that catches (i.e.: records in an array) the arguments of the call, so that the loaded plugins can freely call compdef. Then, the cdreplay (compdef-replay) can be used, after compinit will be called (and the original compdef function will become available), to execute all detected compdef calls. To summarize:

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
source "${ZINIT_HOME}/zinit.zsh"

zinit load "some/plugin"
...
compdef _gnu_generic fd  # this will be intercepted by Zinit, because as the compinit
                         # isn't yet loaded, thus there's no such function `compdef'; yet
                         # Zinit provides its own `compdef' function which saves the
                         # completion-definition for later possible re-run with `zinit
                         # cdreplay' or `zicdreplay' (the second one can be used in hooks
                         # like atload'', atinit'', etc.)
...
zinit load "other/plugin"

autoload -Uz compinit
compinit

# -q is for quiet; actually run all the `compdef's saved before `compinit` call
# (`compinit' declares the `compdef' function, so it cannot be used until
# `compinit' is ran; Zinit solves this via intercepting the `compdef'-calls and
# storing them for later use with `zinit cdreplay')

zinit cdreplay -q

This allows to call compinit once. Performance gains are huge, example shell startup time with double compinit: 0.980 sec, with cdreplay and single compinit: 0.156 sec.

Calling compinit With Turbo Mode

If you load completions using wait'' Turbo mode then you can add atinit'zicompinit' to syntax-highlighting plugin (which should be the last one loaded, as their (2 projects, z-sy-h & f-sy-h) documentation state), or atload'zicompinit' to last completion-related plugin. zicompinit is a function that just runs autoload compinit; compinit, created for convenience. There's also zicdreplay which will replay any caught compdefs so you can also do: atinit'zicompinit; zicdreplay', etc. Basically, the whole topic is the same as normal compinit call, but it is done in atinit or atload hook of the last related plugin with use of the helper functions (zicompinit,zicdreplay & zicdclear – see below for explanation of the last one). To summarize:

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share/zinit}"
source "${ZINIT_HOME}/zinit.zsh"

# Load using the for-syntax
zinit lucid wait for \
  "some/plugin"

zinit lucid wait for \
  "other/plugin"

zi for \
    atload"zicompinit; zicdreplay" \
    blockf \
    lucid \
    wait \
  zsh-users/zsh-completions

Ignoring Compdefs

If you want to ignore compdefs provided by some plugins or snippets, place their load commands before commands loading other plugins or snippets, and issue zinit cdclear (or zicdclear, designed to be used in hooks like atload''):

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
source "${ZINIT_HOME}/zinit.zsh"

zi snippet OMZP::git
zi cdclear -q # <- forget completions provided by Git plugin

zi load "some/plugin"
...
zi load "other/plugin"

autoload -Uz compinit
compinit
zi cdreplay -q # <- execute compdefs provided by rest of plugins
zi cdlist # look at gathered compdefs

The cdreplay is important if you use plugins like OMZP::kubectl or asdf-vm/asdf, because these plugins call compdef.

Disabling System-Wide compinit Call (Ubuntu)

On Ubuntu users might get surprised that e.g. their completions work while they didn't call compinit in their .zshrc. That's because the function is being called in /etc/zshrc. To disable this call – what is needed to avoid the slowdown and if user loads any completion-equipped plugins, i.e. almost on 100% – add the following lines to ~/.zshenv:

# Skip the not really helping Ubuntu global compinit
skip_global_compinit=1

Zinit Module

The module is now hosted in its own repository

Hints and Tips

Using ZPFX variable

Zinit uses a special, short named variable $ZPFX to denote a standard "prefix" for installing compiled software. Such, commonly used, prefixes are usually, e.g.: /usr/,/usr/local or $HOME/.local. Basically, when one would want to explain what a prefix-dir is in one sentence, it would be something like: a root directory, under which …/bin,…/share, …/lib sub-dirs are populated with installed binaries, data-files, libraries, etc.

How to use the variable? It is automatically exploited when using configure'' and make'' ices, and user doesn't have to take any actions. This means that the configure command that'll be run will be:

./configure --prefix=$ZPFX

The default location used for $ZPFX is: ~/.local/share/zinit/polaris. You can, for example, set it to $HOME/.local to have the software installed with configure'' and make'' ices installed to that directory.

Typical use cases when working with $ZPFX are, e.g.:

$ ls $ZPFX
$ cd $ZPFX
$ cd $ZPFX/bin  # note: $ZPFX/bin is automatically prepended to $PATH
$ cd $ZPFX/share

Before the configure'' ice appeared one would use $ZPFX as follows:

zinit atclone'./configure --prefix=$ZPFX` atpull'%atclone' make \
        for universal-ctags/ctags

but now it's sufficient to do:

# Will work for any build system
# (supported are: configure, cmake, scons and meson)
zinit configure make for universal-ctags/ctags

To set ZPFX, one should do (in .zshrc before loading zinit):

$ export ZPFX=$HOME/my-software # or: ZPFX=$HOME/.local, etc.

We encourage people to install compiled software with use of $ZPFX and configure'' and make'' ices, to have a nice, clean user-home dir based setup.

Customizing Paths

Following variables can be set to custom values, before sourcing Zinit. The previous global variables like $ZPLG_HOME have been removed to not pollute the namespace – there's single $ZINIT hash instead of 8 string variables. Please update your dotfiles.

declare -A ZINIT  # initial Zinit's hash definition, if configuring before loading Zinit, and then:

There is also $ZPFX, set by default to ~/.local/share/zinit/polaris – a directory where software with Makefile, etc. can be pointed to, by e.g. atclone'./configure --prefix=$ZPFX'.

Non-GitHub (Local) Plugins

Use create subcommand with user name _local (the default) to create plugin's skeleton in $ZINIT[PLUGINS_DIR]. It will be not connected with GitHub repository (because of user name being _local). To enter the plugin's directory use cd command with just plugin's name (without _local, it's optional).

If user name will not be _local, then Zinit will create repository also on GitHub and setup correct repository origin.

Extending Git

There are several projects that provide git extensions. Installing them with Zinit has many benefits:

• all files are under $HOME – no administrator rights needed,
• declarative setup (like Chef or Puppet) – copying .zshrc to different account brings also git-related setup,
• easy update by e.g. zinit update --all.

Below is a configuration that adds multiple git extensions, loaded in Turbo mode, 1 second after prompt, with use of the Bin-Gem-Node annex:

zi as'null' lucid sbin wait'1' for \
  Fakerr/git-recall \
  davidosomething/git-my \
  iwata/git-now \
  paulirish/git-open \
  paulirish/git-recent \
    atload'export _MENU_THEME=legacy' \
  arzzen/git-quick-stats \
    make'install' \
  tj/git-extras \
    make'GITURL_NO_CGITURL=1' \
    sbin'git-url;git-guclone' \
  zdharma-continuum/git-url

Target directory for installed files is $ZPFX (~/.local/share/zinit/polaris by default).

Changelog

Link to the CHANGELOG.

Support

Zinit is a personal, free-time project with no funding and a huge feature request backlog. If you love it, consider supporting its development via GitHub Sponsors [pending]. Any help counts!

Getting Help and Community

Do you need help or wish to get in touch with other Zinit users?

• Open a discussion.

• Or via reach out via Gitter