🇺🇸 🇯🇵

Zsh Plugin Manager

Pros.

• Can manage everything
  • Zsh plugins/UNIX commands on GitHub and Bitbucket
  • Gist files (gist.github.com)
  • Externally managed plugins e.g., oh-my-zsh and prezto plugins/themes
  • Binary artifacts on GitHub Releases
  • Local plugins
  • etc. (you can add your own sources!)
• Super-fast parallel installation/update
• Support for lazy-loading
• Branch/tag/commit support
• Post-update, post-load hooks
• Dependencies between packages
• Unlike antigen, no ZSH plugin file (*.plugin.zsh) required
• Interactive interface (fzf, peco, zaw, and so on)
• Cache mechanism for reducing the startup time

DEMO:

Installation

latest	stable

The best way

$ curl -sL zplug.sh/installer | zsh

If you wonder this installation, please check it out:

• zplug/installer

Using Homebrew (OS X)

$ brew install zplug

Manually

Cloning from GitHub, and source init.zsh:

$ export ZPLUG_HOME=/path/to/.zplug
$ git clone https://github.com/zplug/zplug $ZPLUG_HOME

Requirements

• zsh: version 4.3.9 or higher
• git: version 1.7 or higher
• awk: An AWK variant that's not mawk

Usage

Add a zplug section to your .zshrc:

1. List the packages with zplug commands
2. zplug load to source the plugins and add commands to your $PATH

Example

source ~/.zplug/init.zsh

# Make sure to use double quotes
zplug "zsh-users/zsh-history-substring-search"

# Use the package as a command
# And accept glob patterns (e.g., brace, wildcard, ...)
zplug "Jxck/dotfiles", as:command, use:"bin/{histuniq,color}"

# Can manage everything e.g., other person's zshrc
zplug "tcnksm/docker-alias", use:zshrc

# Disable updates using the "frozen" tag
zplug "k4rthik/git-cal", as:command, frozen:1

# Grab binaries from GitHub Releases
# and rename with the "rename-to:" tag
zplug "junegunn/fzf-bin", \
    from:gh-r, \
    as:command, \
    rename-to:fzf, \
    use:"*darwin*amd64*"

# Supports oh-my-zsh plugins and the like
zplug "plugins/git",   from:oh-my-zsh

# Also prezto
zplug "modules/prompt", from:prezto

# Load if "if" tag returns true
zplug "lib/clipboard", from:oh-my-zsh, if:"[[ $OSTYPE == *darwin* ]]"

# Run a command after a plugin is installed/updated
# Provided, it requires to set the variable like the following:
# ZPLUG_SUDO_PASSWORD="********"
zplug "jhawthorn/fzy", \
    as:command, \
    rename-to:fzy, \
    hook-build:"
    {
        make
        sudo make install
    } &>/dev/null
    "

# Supports checking out a specific branch/tag/commit
zplug "b4b4r07/enhancd", at:v1
zplug "mollifier/anyframe", at:4c23cb60

# Can manage gist file just like other packages
zplug "b4b4r07/79ee61f7c140c63d2786", \
    from:gist, \
    as:command, \
    use:get_last_pane_path.sh

# Support bitbucket
zplug "b4b4r07/hello_bitbucket", \
    from:bitbucket, \
    as:command, \
    hook-build:"chmod 755 *.sh", \
    use:"*.sh"

# Group dependencies
# Load "emoji-cli" if "jq" is installed in this example
zplug "stedolan/jq", \
    from:gh-r, \
    as:command, \
    rename-to:jq
zplug "b4b4r07/emoji-cli", \
    on:"stedolan/jq"
# Note: To specify the order in which packages should be loaded, use the defer
#       tag described in the next section

# Set the priority when loading
# e.g., zsh-syntax-highlighting must be loaded
# after executing compinit command and sourcing other plugins
# (If the defer tag is given 2 or above, run after compinit command)
zplug "zsh-users/zsh-syntax-highlighting", defer:2

# Can manage local plugins
zplug "~/.zsh", from:local

# Load theme file
zplug 'dracula/zsh', as:theme

# Install plugins if there are plugins that have not been installed
if ! zplug check --verbose; then
    printf "Install? [y/N]: "
    if read -q; then
        echo; zplug install
    fi
fi

# Then, source plugins and add commands to $PATH
zplug load --verbose

Finally, use zplug install to install your plugins and reload .zshrc.

1. Options for zplug

Option	Description
--help	Display the help message
--version	Display the version of zplug
--log	Show the error log (for developer)

2. Commands for zplug

Command	Description	Options
install	Install packages in parallel	(None)
load	Source installed plugins and add installed commands to $PATH	--verbose
list	List installed packages (more specifically, view the associative array $zplugs)	--select
update	Update installed packages in parallel	--select,--force
check	Return true if all packages are installed, false otherwise	--verbose
status	Check if the remote repositories are up to date	--select
clean	Remove repositories which are no longer managed	--force,--select
clear	Remove the cache file	(None)
info	Show the information such as the source URL and tag values for the given package	(None)

Take a closer look

# zplug check returns true if all packages are installed
# Therefore, when it returns false, run zplug install
if ! zplug check; then
    zplug install
fi

# source plugins and add commands to the PATH
zplug load

# zplug check returns true if the given repository exists
if zplug check b4b4r07/enhancd; then
    # setting if enhancd is available
    export ENHANCD_FILTER=fzf-tmux
fi

Let zplug manage zplug

To manage zplug itself like other packages, write the following in your .zshrc.

zplug "zplug/zplug"

All that's left is to run zplug update.

3. Tags for zplug

truthy is any of true, yes, on, 1 and falsy is any of false, no, off, 0.

Tag	Description	Value (default)	Example
as	Specify whether to register the package as plugins or commands	plugin,command,theme (plugin)	as:command
use	Specify the pattern of the files to source (for plugin) or the relative path to add to the $PATH (for command) / With from:gh-r, zplug tries to guess which file to use from your OS and architecture. You can manually specify use:"*darwin*{amd,386}*" if that doesn't get the right file.	glob (use:"*.zsh")	use:bin,use:"*.sh", use:*darwin*
ignore	Similar to use tag, but specify pattern of files you want to ignore (see also #56)	glob (-)	ignore:"some_*.zsh"
from	Specify where to get the package from	github,bitbucket, gh-r,gist, oh-my-zsh,prezto,local (github)	from:gh-r
at	Specify branch/tag/commit to install	revision (master)	at:v1.5.6
rename-to	Specify the filename you want to rename the command to (use this only with as:command)	filename (-)	rename-to:fzf
dir	Installed directory of the package	READ ONLY	dir:/path/to/user/repo
if	Specify the conditions under which to install and use the package	boolean (-)	if:"[ -d ~/.zsh ]"
hook-build	Commands to after installation/update	commands (-)	hook-build:"make install"
hook-load	Commands to after loading	commands (-)	hook-load:"echo 'Loaded!'"
frozen	Do not update unless explicitly specified	truthy,falsy (false)	frozen:1
on	Load this package only if a different package is installed	package	on:user/repo
defer	Defers the loading of a package. If the value is 2 or above, zplug will source the plugin after compinit (see also #26)	0..3 (0)	defer:2
lazy	Whether it is an autoload function or not	truthy,falsy (false)	lazy:true
depth	The number of commits to include in the cloned repository. 0 means the whole history.	Any non-negative integer	depth:10

Changing the defaults

You can use zstyle to change the default value. The format is:

zstyle ":zplug:tag" tag_name new_default_value

For example, if you have a lot of commands and not so many plugins, (i.e. if you find yourself specifying as:command often), you can do:

zstyle ":zplug:tag" as command

The default value for all tags can be changed in this way.

Available on CLI

You can register packages to zplug from the command-line. If you use zplug from the command-line, it is possible to add stuff more easily with the help of powerful zsh completions.

In this case, zplug spit out its settings to $ZPLUG_LOADFILE instead of .zshrc. If you launch new zsh process, zplug load command automatically search this file and run source command.

See ZPLUG_LOADFILE for other usage of ZPLUG_LOADFILE.

4. Environment variables for zplug

ZPLUG_HOME

Defaults to ~/.zplug. zplug will store/load packages in this directory. The directory structure is shown below.

$ZPLUG_HOME
|-- bin
|   `-- some_command -> ../repos/username_A/reponame1/some_command
`-- repos
    |-- username_A
    |   |-- reponame1
    |   |   |-- README.md
    |   |   `-- some_command
    |   `-- reponame2
    |       |-- README.md
    |       `-- some_plugin.zsh
    `-- username_B
        `-- reponame1

If you specify as:command, zplug will see the package as a command and create a symbolic link of the same name (if you want to rename it, use the rename-to: tag) in $ZPLUG_HOME/bin. Because zplug adds $ZPLUG_HOME/bin to the $PATH, you can run that command from anywhere.

ZPLUG_THREADS

The number of threads zplug uses when installing/updating. The default value is 16.

ZPLUG_PROTOCOL

Defaults to HTTPS. Valid options are HTTPS and SSH. Unless you have a specific reason, you should use the HTTPS protocol.

For more information, see also Which remote URL should I use? - GitHub Help

ZPLUG_FILTER

Defaults to fzf-tmux:fzf:peco:percol:zaw. When --select option is specified, the first element in the colon-separated list that exists in the $PATH will be used by zplug as the interactive filter. You can also use spaces and double quotes in ZPLUG_FILTER like: fzf-tmux -d "10%":/path/to/peco:my peco.

ZPLUG_LOADFILE

Defaults to $ZPLUG_HOME/packages.zsh. This file is used to add plugins from zplug on the command-line. It is also a useful place to isolate your packages list from .zshrc. Rather than cluttering your .zshrc with many lines enumerating packages, you can put them in a separate file and set ZPLUG_LOADFILE to its path.

ZPLUG_USE_CACHE

Defaults to true. If this variable is true, zplug will use cache files to speed up the load process. The cache files are saved under the $ZPLUG_CACHE_DIR directory. If you want to clear the cache, please run zplug clear or do the following:

$ ZPLUG_USE_CACHE=false zplug load

ZPLUG_CACHE_DIR

Defaults to $ZPLUG_HOME/.cache. You can change where the cache file is saved, for example, ~/.cache/zplug.

ZPLUG_REPOS

Defaults to $ZPLUG_HOME/repos. You can change where the repositories are cloned in case you want to manage them separately.

ZPLUG_SUDO_PASSWORD

Defaults to ''. You can set sudo password for zplug's hook-build tag. However, this variable should not be managed in dotfiles and so on.

# your .zshrc
source ~/.zshrc_secret
zplug "some/command", hook-build:"make && sudo make install"

External commands

zplug, like git(1), supports external commands. These are executable scripts that reside somewhere in the PATH, named zplug-cmdname, which can be invoked with zplug cmdname. This allows you to create your own commands without modifying zplug's internals. Instructions for creating your own commands can be found in the docs. Check out the sample zplug-env external command for an example.

V.S.

zplug is the fastest among the famous zsh plugin managers. Numbers? Here they are:

Note

• Not antigen 💉 but zplug 🌺 will be here for you from now on.
• 🌺 It was heavily inspired by vim-plug, neobundle.vim and the like.

Other resources

awesome-zsh-plugins is a list of ZSH plugins, themes and completions that you can use with zplug.

For migration from antigen, zgen, or zplug v1, check out the wiki page.

License

MIT (c) @b4b4r07