Repository files navigation

• Zinit Wiki
• Install
  • Automatic
  • Manual
• Usage
  • Introduction
  • Plugins and snippets
  • Upgrade Zinit and plugins
  • Turbo and lucid
  • Migration
• Frequently Asked Questions
  • Usezi ice svn if a plugin/snippet requires an entire subdirectory
  • Usezi 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
  • Callingcompinit Without Turbo Mode
  • Callingcompinit With Turbo Mode
  • Ignoring Compdefs
  • Disabling System-Widecompinit Call
    • Ubuntu
    • NixOS
• 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 othersites. Its characteristics are:

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

2. The plugin manager givesreports from plugin loadings describing whataliases, functions,bindkeys, Zlewidgets, zstyles,completions, variables,PATH andFPATH elements a plugin has set up. This allows one toquickly familiarize oneself with a new plugin and provides rich and easy-to-digest information which might be helpfulon various occasions.

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

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

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 toKSH_ARRAYS and other options typically causing compatibility problems.

6. Zinit supports special, dedicatedpackages that offload the user from providing long and complex commands. Seethezinit-packages repository for a growing, complete list ofZinit packages and theWiki page for an articleabout the feature.

7. Also, specialized Zinit extensions — calledannexes — have the ability to extend the plugin manager with newcommands, URL-preprocessors (used by e.g.:zinit-annex-readurl annex), post-install and post-updatehooks, and much more. See thezdharma-continuum organization for a growing,complete list of available Zinit extensions and refer to theWiki article for an introduction on creating your annex.

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

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 willbe added to the bottom. The lines will be sourcingzinit.zsh and setting up completion for commandzinit.

After installing and reloading the shell, compile Zinit via:

zinit self-update

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 sourcezinit.zsh aftercompinit, add the following snippet after sourcingzinit.zsh:

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

Reload Zsh to install Zinit:

exec zsh

Various paths can be customized; see sectionCustomizing Paths.

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

Plugins can be loaded usingload orlight.

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 withsnippet.

zinit snippet<URL>

Such lines should be added to.zshrc. Snippets are cached locally. Use the-f option to download a new version of asnippet orzinit update {URL}. You can also usezinit 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-autosuggestionszinit light zdharma-continuum/fast-syntax-highlighting# Snippetzinit snippet https://gist.githubusercontent.com/hightemp/5071909/raw/

Prompt(Theme) Example

This ispowerlevel10k,pure,starship sample:

# Load powerlevel10k themezinit ice depth"1"# git clone depthzinit light romkatv/powerlevel10k# Load pure themezinit 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.zshzinit 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

Zinit can be updated toself-update and plugins toupdate.

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

Turbo and lucid are the most used options.

zinit icewait# wait is the same as wait"0"zinit load zdharma-continuum/history-search-multi-wordzinit ice wait"2"# load after 2 secondszinit load zdharma-continuum/history-search-multi-wordzinit icewait# also be used in `light` and `snippet`zinit snippet https://gist.githubusercontent.com/hightemp/5071909/raw/

zinit icewait lucidzinit load zdharma-continuum/history-search-multi-word

F&A: What isice?

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

zinit snippet<URL># Raw Syntax with URLzinit 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 Syntaxzi snippet https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/clipboard.zshzi snippet https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/termsupport.zsh# OMZ Shorthand Syntaxzi snippet OMZ::lib/clipboard.zshzi snippet OMZ::lib/termsupport.zsh# OMZL Shorthand Syntaxzi snippet OMZL::clipboard.zshzi snippet OMZL::termsupport.zsh

## Oh My Zsh SettingZSH_THEME="robbyrussell"## Zinit Setting# Must Load OMZ Git libraryzi snippet OMZL::git.zsh# Must Load OMZ Async prompt libraryzi snippet OMZL::async_prompt.zsh # Load Git plugin from OMZzi snippet OMZP::gitzi cdclear -q# <- forget completions provided up to this momentsetopt promptsubst# Load Promptzi snippet OMZT::robbyrussell

## Oh My Zsh SettingZSH_THEME="alpharized"## Zinit Setting# Must Load OMZ Git libraryzi snippet OMZL::git.zsh# Load Git plugin from OMZzi snippet OMZP::gitzi cdclear -q# <- forget completions provided up to this momentsetopt promptsubst# Load Promptzi light NicoSantangelo/Alpharized

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

## Oh-My-Zsh Settingplugins=(  git  dotenv  rake  rbenv  ruby)## Zinit Settingzi snippet OMZP::gitzi snippet OMZP::dotenvzi snippet OMZP::rakezi snippet OMZP::rbenvzi snippet OMZP::ruby

zi ice svnzi snippet OMZP::gitfastzi ice svnzi snippet OMZP::osx

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

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

## Prezto Settingzstyle':prezto:load' pmodule'environment''terminal'## Zinit Setting# Raw Syntaxzi snippet https://github.com/sorin-ionescu/prezto/blob/master/modules/environment/init.zshzi snippet https://github.com/sorin-ionescu/prezto/blob/master/modules/terminal/init.zsh# PZT Shorthand Syntaxzi snippet PZT::modules/environmentzi snippet PZT::modules/terminal# PZTM Shorthand Syntaxzi snippet PZTM::environmentzi snippet PZTM::terminal

zi ice svnzi snippet PZTM::dockerzi ice svnzi 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  svnzi snippet PZTM::completion

# Load ohmyzsh basezgen oh-my-zshzi snippet OMZL::<ALL OF THEM># Load ohmyzsh pluginszgen oh-my-zsh<PATH>zi snippet OMZ::<PATH>

# Load Preztozgen preztozi snippet PZTM::<COMMENT's List> # environment terminal editor history directory spectrum utility completion prompt# Load prezto pluginszgen prezto <modulename>zi snippet PZTM::<modulename># Load a repo as Prezto pluginszgen pmodule <reponame> <branch>zi ice ver"<branch>"zi load <repo/plugin># Set prezto optionszgen 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>

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/zinitfor \    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-programszi 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 & atpullzi 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 thezinit-configs repository, where users have uploaded their~/.zshrc and Zinit configurations. Feel free tosubmityour~/.zshrc there if it contains Zinit commands.

You can also check out theGallery of Zinit Invocations forsome additional examples.

Also, two articles on the Wiki present an example setuphere andhere.

Followingice modifiers are to bepassed tozinit ice ... to obtain described effects. The wordice means something that's added (like ice to a drink) – and inZinit it means adding modifier to a nextzinit command, and also something that's temporary because it melts – andthis means that the modification will last only for asingle nextzinit command.

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

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

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

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

List plugins that are compiled.

zinit [options] compile PLUGIN

List plugins that are compiled.

zinit compiled

List plugins that are compiled.

zinit [options] uncompile PLUGIN

To update Zinit issuezinit self-update in the command line.

To update all plugins and snippets, issuezinit update. If you wish to update only a single plugin/snippet insteadissuezinit 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 theatpullice modifier. For example, writingzinit ice atpull'./configure' before loading a plugin will execute./configureafter a successful update. Refer toIce Modifiers for more information.

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

With no Turbo mode in use, compinit can be called normally, i.e.: asautoload compinit; compinit. This should be doneafter loading of all plugins and before possibly callingzinit cdreplay.

Thecdreplay subcommand is provided to re-play all caughtcompdef calls. Thecompdef calls are used to define acompletion for a command. For example,compdef _git git defines that thegit command should be completed by a_gitfunction.

Thecompdef function is provided bycompinit call. As it should be called later, after loading all of the plugins,Zinit provides its owncompdef function that catches (i.e.: records in an array) the arguments of the call, so thatthe loaded plugins can freely callcompdef. Then, thecdreplay (compdef-replay) can be used, aftercompinit willbe called (and the originalcompdef function will become available), to execute all detectedcompdef calls. Tosummarize:

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 compinitcompinit# -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 doublecompinit:0.980 sec, withcdreplay and singlecompinit:0.156 sec.

If you load completions usingwait'' Turbo mode then you can addatinit'zicompinit' to syntax-highlighting plugin(which should be the last one loaded, as their (2 projects,z-sy-h &f-sy-h) documentation state), oratload'zicompinit'to last completion-related plugin.zicompinit is a function that just runsautoload compinit; compinit, created forconvenience. There's alsozicdreplay which will replay any caught compdefs so you can also do:atinit'zicompinit; zicdreplay', etc. Basically, the whole topic is the same as normalcompinit call, but it is doneinatinit oratload 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-syntaxzinit lucidwaitfor \"some/plugin"zinit lucidwaitfor \"other/plugin"zifor \    atload"zicompinit; zicdreplay" \    blockf \    lucid \wait \  zsh-users/zsh-completions

If you want to ignore compdefs provided by some plugins or snippets, place their load commands before commands loadingother plugins or snippets, and issuezinit cdclear (orzicdclear, designed to be used in hooks likeatload''):

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"source"${ZINIT_HOME}/zinit.zsh"zi snippet OMZP::gitzi cdclear -q# <- forget completions provided by Git pluginzi load"some/plugin"...zi load"other/plugin"autoload -Uz compinitcompinitzi cdreplay -q# <- execute compdefs provided by rest of pluginszi cdlist# look at gathered compdefs

Thecdreplay is important if you use plugins likeOMZP::kubectl orasdf-vm/asdf, because these plugins callcompdef.

On some systems, users might be surprised to see that completions work even though they didn’t callcompinit in their~/.zshrc. This happens becausecompinit is being called from/etc/zshrc. To disable this behavior -- which isrecommended to avoid slow startup, especially if you load plugins that bring their own completions (which is almostalways the case) -- follow the instructions for your system below:

On Ubuntu, the globalcompinit call can be disabled on a per-user basis by adding the following lines to a users~/.zshenv:

# Skip the not really helping Ubuntu global compinitskip_global_compinit=1

On NixOS, the globalcompinit call can be disabled system-wide by setting the following option in your/etc/nixos/configuration.nix:

# Disable global completion init to speed up `compinit` call in `~/.zshrc`.programs.zsh.enableGlobalCompInit = false;

Don't forget to add thecompinit call to every user's~/.zshrc! Otherwise completions for system packages might notwork.

The module is now hostedin its own repository

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 toexplain 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 usingconfigure'' andmake'' ices, and user doesn't haveto take any actions. This means that theconfigure 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/.localto have the software installed withconfigure'' andmake'' ices installed to that directory.

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

ls$ZPFXcd$ZPFXcd$ZPFX/bin# note: $ZPFX/bin is automatically prepended to $PATHcd$ZPFX/share

Before theconfigure'' 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 makefor universal-ctags/ctags

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

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

We encourage people to install compiled software with use of$ZPFX andconfigure'' andmake'' ices, to have anice, clean user-home dir based setup.

Following variables can be set to custom values, before sourcing Zinit. The previous global variables like$ZPLG_HOMEhave been removed to not pollute the namespace – there's single$ZINIT hash instead of8 string variables. Pleaseupdate 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 withMakefile,etc. can be pointed to, by e.g.atclone'./configure --prefix=$ZPFX'.

Usecreate subcommand with user name_local (the default) to create plugin's skeleton in$ZINIT[PLUGINS_DIR]. Itwill be not connected with GitHub repository (because of user name being_local). To enter the plugin's directory usecd 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.

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 theBin-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).

Link to theCHANGELOG.

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

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

• Open a discussion.

• Or via reach out via Matrix