Zinit

A quick reference guide for the Zinit Zsh plugin manager. Zinit is known for its speed and powerful features like “ices” (modifiers), snippets, and annexes.

Installation

To install Zinit, run the following command in your Zsh terminal. This will add the necessary lines to your .zshrc file to get you started.

bash -c "$(curl -fsSL https://git.io/zinit-install)"

After running, restart your shell or source your configuration with source ~/.zshrc.

Basic Usage

All plugin and snippet definitions go in your .zshrc file.

Loading Plugins

Zinit offers two main ways to load plugins: light and load.

zinit light <user>/<repo>: The fastest way. It clones the repo and sources the main plugin file. It does not support “ices”.
zinit load <user>/<repo>: Slower but more powerful. It enables the use of “ices” (modifiers) for advanced loading logic.

# ~/.zshrc
 
# --- Simple plugin loading (fastest method) ---
zinit light zdharma-continuum/fast-syntax-highlighting
zinit light zsh-users/zsh-autosuggestions
zinit light zsh-users/zsh-completions
 
# --- Loading from Oh My Zsh repositories ---
zinit light ohmyzsh/plugins/git
zinit light ohmyzsh/plugins/sudo
 
# --- Use `load` when you need to apply "ices" ---
zinit ice lucid wait'0' atinit'zpcompinit'
zinit load zsh-users/zsh-completions

Loading Snippets

Snippets are single files (not whole repositories) that can be sourced directly. This is extremely efficient for small functions or completions that don’t need a full repository.

# Syntax: zinit snippet <URL_to_raw_file>
 
# Example: Load a single completion file from a repository
zinit snippet https://github.com/docker/cli/blob/master/contrib/completion/zsh/_docker

Managing Plugins & Snippets (CLI Commands)

These commands are run directly in your terminal to manage your Zinit installation.

Command	Description
`zinit update`	Update all plugins and snippets.
`zinit update <plugin>`	Update a specific plugin (e.g., `zinit update zsh-users/zsh-autosuggestions`).
`zinit list`	List all loaded plugins and snippets.
`zinit times`	Show the load times for each plugin. Essential for performance tuning.
`zinit report <plugin>`	Show detailed information about a specific plugin.
`zinit delete <plugin>`	Uninstall a plugin and remove its directory.
`zinit clean`	Delete any plugins that are no longer listed in your `.zshrc`.
`zinit compile <plugin>`	Compile a plugin with `zcompile` for a speed boost.
`zinit uncompile <plugin>`	Remove the compiled version of a plugin.

”Ices” (Load Modifiers)

Ices are the superpower of Zinit. They are special commands that modify the loading behavior of the next zinit load or zinit light command that follows them.

Syntax: zinit ice <ice-name>[<value>] [<another-ice>...]

Common Ices

Ice	Description
`as"plugin\|command\|theme"`	Load the target as a plugin, a binary command, or a theme.
`lucid`	(Performance) Loads the plugin in the background after the prompt is shown. Highly recommended.
`wait"[n]"`	(Performance) Delays loading by `n` seconds (e.g., `wait'1'`). `wait'0'` is equivalent to `lucid`.
`pick"path/to/file"`	Source only the specified file(s) from the plugin directory.
`atinit"command"`	Execute a command before the plugin is sourced. Useful for setup tasks like `zpcompinit`.
`atpull"command"`	Execute a command every time the plugin is updated (`git pull`).
`atclone"command"`	Execute a command only once, right after the plugin is cloned. Useful for running `make` or build scripts.
`if"[[ condition ]]"`	Load the plugin only if the Zsh condition is true. E.g., `if"(( $+commands[exa] ))"`.
`on-update-of"plugin"`	When the specified plugin is updated, also update this one.
`from"gh-r"`	Download from GitHub Releases instead of cloning. Requires `zinit-annex-patch-dl`.
`mv"source -> target"`	Rename a file or directory within the plugin’s directory after cloning.

Annexes (Extensions)

Annexes add new features and ices to Zinit itself. They are loaded like regular plugins.

# ~/.zshrc
 
# Provides the `bin-gem-node` ice for installing binaries/gems/npm packages
zinit light zdharma-continuum/zinit-annex-bin-gem-node
 
# Provides download/patching features and the `from"gh-r"` ice
zinit light zdharma-continuum/zinit-annex-patch-dl
 
# Provides Turbo mode (using zsh/zutil module) and `wait` ice
zinit light zdharma-continuum/zinit-annex-as-monitor

Practical Examples

Here are some real-world examples combining various features.

# ~/.zshrc
 
# 1. Load zsh-syntax-highlighting with Turbo mode (lucid) for a fast prompt
zinit ice lucid
zinit light zdharma-continuum/fast-syntax-highlighting
 
# 2. Load fzf-zsh-plugin, but only if the `fzf` command exists
zinit ice if"(( $+commands[fzf] ))"
zinit light Aloxaf/fzf-tab
 
# 3. Install a binary from GitHub Releases (e.g., exa)
# `zinit-annex-patch-dl` is required for `from"gh-r"`
zinit ice from"gh-r" as"command" mv"exa* -> exa"
zinit light ogham/exa
 
# 4. Load a plugin that needs to be compiled after cloning
zinit ice atclone"make" atpull"%atclone" pick"async.zsh"
zinit load mafredri/zsh-async
 
# 5. Conditionally load a theme based on the terminal type
zinit ice if'[[ "$TERM" == "xterm-256color" ]]'
zinit light romkatv/powerlevel10k

Quartz 🪬

Explorer