NOTE: PZ is now Antidote, a feature-compatible implementation of the legacy Antibody plugin manager. This change introduces breaking changes to legacy PZ. The original PZ will remain available on the "pz" branch.

PZ - Plugins for Zsh made easy-pz

A plugin manager for Zsh doesn't have to be complicated to be powerful. PZ doesn't try to be clever when it can be smart. PZ is a full featured, fast, and easy to understand plugin manager encapsulated in a single, small, clean Zsh script.

PZ does just enough to manage your Zsh plugins really well, and then gets out of your way. And it's unit tested too to make sure it works as expected!

Plugins for Zsh made easy-pz.

The help is pretty helpful. Run pz help:

pz - Plugins for Zsh made easy-pz

usage:
  pz <command> [<flags...>|<arguments...>]

commands:
  help      display this message
  clone     download a plugin
  initfile  display the plugin's init file
  list      list all plugins
  prompt    load a prompt plugin
  pull      update a plugin, or all plugins
  source    load a plugin
  zcompile  compile your plugins' zsh files

You can also get extended help for commands by running pz help <command>:

$ pz help source
usage:
  pz source <plugin> [<subpath>]

args:
  plugin   shorthand user/repo or full git URL
  subpath  subpath within plugin to use instead of root path

examples:
  pz source ohmyzsh
  pz source ohmyzsh/ohmyzsh lib/git
  pz source ohmyzsh/ohmyzsh plugins/extract
  pz source zsh-users/zsh-autosuggestions
  pz source https://github.com/zsh-users/zsh-history-substring-search
  pz source [email protected]:zsh-users/zsh-completions.git

To install pz, simply clone the repo...

git clone https://github.com/mattmc3/pz.git ~/.config/zsh/plugins/pz

...and source pz from your .zshrc

source ~/.config/zsh/plugins/pz/pz.zsh

- Or -

You could add this snippet for total automation in your .zshrc

PZ_PLUGIN_HOME="${ZDOTDIR:-~/.config/zsh}/plugins"
[[ -d $PZ_PLUGIN_HOME/pz ]] ||
  git clone https://github.com/mattmc3/pz.git $PZ_PLUGIN_HOME/pz
source $PZ_PLUGIN_HOME/pz/pz.zsh

Downloading a plugin from a git repository referred to as cloning. You can clone a plugin with partial or full git paths:

# clone with the user/repo shorthand (assumes github.com)
pz clone zsh-users/zsh-autosuggestions

# or, clone with a git URL
pz clone https://github.com/zsh-users/zsh-history-substring-search
pz clone [email protected]:zsh-users/zsh-completions.git

You can even rename a plugin if you prefer to call it something else:

# call it autosuggest instead
pz clone zsh-users/zsh-autosuggestions autosuggest

Loading a plugin means you source its primary plugin file. You can source a plugin to use it in your interactive Zsh sessions.

pz source zsh-history-substring-search

If you haven't cloned a plugin already, you can still source it. It will be cloned automatically, but in order to do that you will need to use its longer name or a full git URL:

pz source zsh-users/zsh-history-substring-search
pz source https://github.com/zsh-users/zsh-autosuggestions

You can use prompt plugins too, which will set your theme. Prompt plugins are special and are handled a little differently than sourcing regular plugins.

pz prompt sindresorhus/pure

Zsh has builtin functionality for switching and managing prompts. Running this Zsh builtin command will give you a list of the prompt themes you have available:

prompt -l

If you would like to make more prompt themes available, you can use the -a flag. This will not set the theme, but make it available to easily switch during your Zsh session.

For example, in your .zshrc add the following:

# .zshrc
# make a few other great prompts available
pz prompt -a miekg/lean
pz prompt -a romkatv/powerlevel10k

# and then set your default prompt to pure
pz prompt sindresorhus/pure

You can then switch to an available prompt in your interactive Zsh session:

$ # list available prompts
$ prompt -l
Currently available prompt themes:
adam1 adam2 bart bigfade clint default elite2 elite fade fire off ...

$ # now, switch to a different prompt
$ prompt pure

You can update a single plugin:

pz pull mattmc3/pz

Or, update all your plugins:

pz pull

If you use Oh My Zsh, you are probably familiar with $ZSH_CUSTOM, which is where you can add your own plugins to Oh My Zsh. By default, $ZSH_CUSTOM resides in ~/.oh-my-zsh/custom, but you can put it anywhere.

PZ is a stand alone plugin manager, but it also works really well to augment Oh My Zsh. This is handy since Oh My Zsh doesn't have a way to manage external plugins itself. To use PZ to manage your external Oh My Zsh plugins, simply set your $PZ_PLUGIN_HOME variable to $ZSH_CUSTOM/plugins. For example, try adding this snippet to your .zshrc:

# set omz paths somewhere in your script
ZSH=${ZSH:-${ZDOTDIR:-~}/.oh-my-zsh}
ZSH_CUSTOM=${ZSH_CUSTOM:-$ZSH/custom}

# set PZ's home to your omz custom path
PZ_PLUGIN_HOME=$ZSH_CUSTOM

# get PZ if you haven't already
[[ -d $PZ_PLUGIN_HOME/pz ]] ||
  git clone https://github.com/mattmc3/pz.git $PZ_PLUGIN_HOME/pz

# clone anything you need that omz didn't provide
pz clone zsh-users/zsh-autosuggestions
pz clone zsh-users/zsh-syntax-highlighting

# no need to source pz.zsh yourself if you put it in your plugins array
plugins=(... pz zsh-autosuggestions zsh-syntax-highlighting)

# source omz like normal
source $ZSH/oh-my-zsh.sh

Alternatively, if prefer to have PZ drive your configuration rather than Oh My Zsh, but still want Oh My Zsh plugins and features, you can setup your config this way instead:

# get PZ if you haven't already
[[ -d $PZ_PLUGIN_HOME/pz ]] ||
  git clone https://github.com/mattmc3/pz.git $PZ_PLUGIN_HOME/pz

# source regular plugins
pz source mafredri/zsh-async
pz source zsh-users/zsh-autosuggestions

# source OMZ libs and plugins
ZSH=$PZ_PLUGIN_HOME/ohmyzsh
pz source ohmyzsh/ohmyzsh lib/git
pz source ohmyzsh/ohmyzsh plugins/git
pz source ohmyzsh/ohmyzsh plugins/heroku
pz source ohmyzsh/ohmyzsh plugins/brew
pz source ohmyzsh/ohmyzsh plugins/fzf

# make the prompt pretty
pz prompt sindresorhus/pure

# always source syntax highlighting plugin last
pz source zsh-users/zsh-syntax-highlighting

PZ stores your plugins in your $ZDOTDIR/plugins directory. If you don's use $ZDOTDIR, then ~/.config/zsh/plugins is used.

But, if you prefer to store your plugins someplace else, you can always change the default plugin location. Do this by setting the PZ_PLUGIN_HOME variable in your .zshrc before sourcing PZ:

# use a custom directory for pz plugins
PZ_PLUGIN_HOME=~/.pzplugins

Also note that it is recommended that you store PZ in the same place as your other plugins so that pz pull will update PZ.

If you store your Zsh configuration in a dotfiles reporitory, it is recommended to add your preferred $PZ_PLUGIN_HOME to your .gitignore file.

Don't want to use GitHub.com for your plugins? Feel free to change the default git URL with this zstyle in your .zshrc:

# bitbucket.org or gitlab.com or really any git service
zstyle :pz:clone: gitserver bitbucket.org

An example .zshrc might look something like this:

### ${ZDOTDIR:-~}/.zshrc

# setup your environment
...

# then setup pz
PZ_PLUGIN_HOME="${ZDOTDIR:-~/.config/zsh}/plugins"
[[ -d $PZ_PLUGIN_HOME/pz ]] ||
  git clone https://github.com/mattmc3/pz.git $PZ_PLUGIN_HOME/pz
source $PZ_PLUGIN_HOME/pz/pz.zsh

# source plugins from github
pz source zsh-users/zsh-autosuggestions
pz source zsh-users/zsh-history-substring-search
pz source zsh-users/zsh-completions
pz source zsh-users/zsh-syntax-highlighting

# source ohmyzsh plugins
pz source ohmyzsh/ohmyzsh plugins/colored-man-pages

# set your prompt
pz prompt sindresorhus/pure

# -or- use oh-my-zsh themes instead of a prompt plugin
pz source ohmyzsh lib/git
pz source ohmyzsh lib/theme-and-appearance
pz source ohmyzsh themes/robbyrussell