ZPLUG(1)

📦 version 2.4.2, in debian bookworm, debian trixie, nixpkgs unstable, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💅 ZPLUG(1) — the ZPLUG Manual, section 1 🎀

okay bestie, sit down, hydrate, and let me tell you about zplug ✨ this is the manual page for it, section 1, and it's gonna be a whole journey. no cap.

🌸 NAME 🌸

zplug — a next-generation plugin manager for zsh 🦋

✨ SYNOPSIS ✨

zplug ["username/reponame"[, tag:"value"[,...]]]
    [<command> [<options>] [<package>]]

so when we say package anywhere in this page, we mean a string shaped exactly like this: "username/reponame". that's the vibe. that's the format. periodt. 💖

👑 DESCRIPTION 👑

zplug is a super-fast next-generation plugin manager for zsh. she can manage everything, literally: zsh plugins, UNIX commands, Gist files, GitHub Releases, local plugins, and so on and so on. and unlike antigen, zplug requires no ZSH plugin file (*.plugin.zsh) — not one, not ever. it's such a fantabulous piece of software, i'm obsessed fr fr 💀💖

here's the whole flex list:

Can manage everything 👑
- Zsh plugins/UNIX commands on GitHub, Gitlab and Bitbucket
- Gist file (gist.github.com)
- Third-party sources e.g., oh-my-zsh and prezto plugins/themes
- Binary artifacts on GitHub Releases
- Local plugins
- etc. (you can add your own sources! yes queen, build your own 🫶)
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 ⭐

💜 OPTIONS 💜

--help — prints the synopsis and a list of all the available commands. your lil cheat sheet bestie 📖
--version — prints zplug's version. that's it, that's the whole job 💁
--log — shows the error log. when things go 💀, look here.

🎀 COMMANDS 🎀

check [--verbose] [package] — checks whether there's at least one item that's not installed. if you hand her a package (username/reponame), she checks if that package is installed. and if you pass the --verbose option, she prints extra debugging information 🔍
clean [--force] [--select] [package] — removes unused packages that are sitting in $ZPLUG_HOME/repos, but only after showing you a yes/no prompt. if you give her a package, she uninstalls that particular package. if the --force option is given, she suppresses the prompt and just uninstalls — no takebacks. and if the --select option is given, she uses the filter you set in $ZPLUG_FILTER so you can interactively pick which package you wanna uninstall 🧹
clear — removes the cache file. bye cache 🫡
install [package] — installs package. go get it ✨
list [--verbose] [--select] [package] — lists installed packages. --select does the same as what's described above 👆
load [--verbose] — loads packages. every package registered with as:plugin gets sourced into the current zsh process, and its parent directory gets added to $fpath. on top of that, all packages with as:command get linked into $ZPLUG_HOME/bin and that bin directory gets added to $PATH. and --verbose does the same as what's described above 👆
info <package> — shows the information like the source URL and the tag values of the package. the tea ☕
status [--select] — fetches the newest version of the installed packages by zplug. --select does the same as what's described above 👆
update [--select] [--force] [package] — updates package. if no package is given, she updates all the registered packages. --select does the same as what's described above 👆

🌈 TAGS 🌈

the values truthy and falsy mean any of "true, yes, on, 1" and "false, no, off, 0", respectively. iykyk 💅

🏷️ Table 1. zplug list of available tags

okay bestie, this is the whole tag menu 💖 every one of these is a lil knob you can twist inside your zplug call, and ngl they're all kind of iconic. going down the list one by one, no skipping, we do not skip. ✨

as — tells zplug whether you're registering this package as commands or as plugins.
- Value: plugin,command,theme (default: plugin)
- Example: as:command
use — sets the pattern of the files to source (when it's a plugin), OR the relative path from the package root of the file you want added to $PATH (when it's a command). super useful, like, for example with from:gh-r you can say use:"*darwin*{amd,386}*" and so on and so forth. and if you wanna use extended glob, bestie, there's a later section about setting the zstyle for that, iykyk. 🦋
- Value: glob (default: use:"*.zsh")
- Example: use:bin,use:"*.sh",use:"*darwin*"
from — which service you're installing from. pick your fave. 🌈
- Value: github,gitlab,bitbucket,gh-r,gist,oh-my-zsh,prezto,local (default: github)
- Example: from:gh-r
at — the branch, tag, or commit you want to use. pin it, queen. 👑
- Value: revision (default: master)
- Example: at:v1.5.6
rename-to — lets you say what filename you want it renamed to (heads up: this one is only valid with as:command).
- Value: filename (default: -)
- Example: rename-to:fzf
dir — the installation directory, and just so you know, this one is managed by zplug itself.
- Value: READ ONLY
- Example: dir:/path/to/user/repo
if — the conditions under which to install and/or use the package. conditional queen behavior. 💅
- Value: commands (default: -)
- Example: if:"[ -d ~/.zsh ]"
hook-build — commands to run after installation/update.
- Value: commands (default: -)
- Example: hook-build:"make install"
hook-load — commands to run after loading. surprise!! 🎀
- Value: commands (default: -)
- Example: hook-load:"echo ´Boo!´"
frozen — do not update this one unless it's explicitly specified. it's giving "don't touch my baby". 🫶
- Value: truthy,falsy (default: no)
- Example: frozen:true
on — dependencies. this package depends on that package, we love a support system. 💜
- Value: package (default: -)
- Example: on:user/repo
lazy — lazy-load it. main character energy, arrives exactly when needed. 😌
- Value: truthy,falsy (default: no)
- Example: lazy:true
depth — how many commits you wanna pull into the cloned repo, bestie. 0 means the whole history, no skips. Value type? Any non-negative integer, so like depth:10 if you're being picky. ✨
defer — delays the loading of a package, iykyk. If the value is 2 or above, zplug will source the plugin after compinit (see also #26). Range is 0..3, defaulting to 0. 💅
ignore — basically use's sibling but for the opposite vibe: specify an exception pattern of files you do not want loaded (see also #56). Takes a glob, default -. 🚫

You can also register packages for zplug straight from the command line, no cap. If you use zplug on the command line you get to flex the command line completions. When you do it this way, zplug writes out the package settings to $ZPLUG_LOADFILE. Then if you launch a new zsh process, the zplug load command will automatically use that file. 🫶 And heads up — you can also use $ZPLUG_LOADFILE to keep your zplug package listing fully isolated from your .zshrc, which is lowkey iconic.

🌸 ENVIRONMENT VARIABLES 🌸

Various zplug commands use the following environment variables, bestie, so let's get into it:

ZPLUG_HOME — defaults to ~/.zplug. This is where zplug stores and loads plugins from. The directory structure is giving:

$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 when registering the package, zplug will recognize the plugin as a command and create a symbolic link of the same name in $ZPLUG_HOME/bin (and yeah, if you wanna rename it, use rename-to). Because zplug adds $ZPLUG_HOME/bin to your $PATH, you can run that command from literally anywhere, just like any other command. 👑

ZPLUG_THREADS — the maximum number of threads zplug should use when installing/updating. Default value is 16. Go off. 🔥
ZPLUG_PROTOCOL — defaults to HTTPS. Valid options for $ZPLUG_PROTOCOL are HTTPS or 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 the --select option is specified in a subcommand, starting from the first element of the colon-separated list, whatever filter found will be used by zplug as the interactive filter. The ZPLUG_FILTER also accepts arguments (e.g. fzf-tmux -d "10%":/path/to/peco:my peco). 🦋
ZPLUG_LOADFILE — defaults to $ZPLUG_HOME/packages.zsh. This file is used to add packages from zplug on the command-line. It's a super useful feature when you wanna isolate your zplug configurations from your .zshrc. And note: you don't need to add packages from the command line to use this feature — you can manually edit this file and it'll work just fine! ✨
ZPLUG_USE_CACHE — defaults to true. If this variable is true, zplug uses a cache file to speed up the loading process. The cache file lives at $ZPLUG_CACHE_DIR ($ZPLUG_HOME/.cache by default). If you wanna 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. Specifies where to save the cache. For example, you can set this to $HOME/.cache/zplug to follow the XDG Base Directory Specification. 🎀
ZPLUG_REPOS — defaults to $ZPLUG_HOME/repos. You can change where the repositories are cloned, in case you wanna manage them separately.
ZPLUG_SUDO_PASSWORD — defaults to ´´. You can set the sudo password for zplug's hook-build tag. However, this variable shoud not be managed in dotfiles and so on. 🙈

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

💜 USING ZSTYLE 💜

You can use zstyle to change the default values for each tag. 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

You can also specify what options to enable in sub shells. Sub shells are used when expanding glob expressions. If you wanna use the extended_glob for example, you can do:

zstyle ":zplug:config:setopt" only_subshell extended_glob

If you set :zplug:config:setopt same_curshell to a truthy value (i.e. true, 1, yes), zplug will enable the options enabled at the point of sourcing zplug (i.e. at the point of source $ZPLUG_HOME/init.zsh). 🌈

⭐ 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 lets you create your own commands without modifying zplug's internals. Instructions for creating your own commands can be found in the docs:

https://github.com/zplug/zplug/blob/master/doc/zplug/External-Commands.md

Check out the sample zplug-env external command for an example. 💖

👑 CONFIGURATION 👑

Add a zplug section to your .zshrc (or $ZPLUG_LOADFILE):

Register packages with the zplug command (zplug "username/reponame")
zplug load to source the plugins and add its commands to your $PATH

source ~/.zplug/zplug

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

# Can manage a plugin 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

# Prohibit updates to a plugin by using the "frozen:" tag
zplug "k4rthik/git-cal", as:command, frozen:1

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

# Support oh-my-zsh plugins and the like
zplug "plugins/git",   from:oh-my-zsh, if:"(( $+commands[git] ))"
zplug "themes/duellj", from:oh-my-zsh, as:theme
zplug "lib/clipboard", from:oh-my-zsh, if:"[[ $OSTYPE == *darwin* ]]"

# Also supports prezto plugins
zplug "modules/osx", from:prezto, if:"[[ $OSTYPE == *darwin* ]]"
zplug "modules/prompt", from:prezto
# Set zstyle before zplug load
zstyle ´:prezto:module:prompt´ theme ´sorin´

# Run a command after a plugin is installed/updated
zplug "tj/n", hook-build:"make install"

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

# Install if "if:" tag returns true
zplug "hchbaw/opp.zsh", if:"(( ${ZSH_VERSION%%.*} < 5 ))"

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

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

# Support Gitlab
zplug "willemmali-sh/chegit", \
    as:command, \
    from:gitlab

# Group dependencies, emoji-cli depends on jq in this example
zplug "stedolan/jq", \
    as:command, \
    from:gh-r \
    rename-to:jq, \
    on:"b4b4r07/emoji-cli"

# Defers the loading of a package
# e.g., zsh-syntax-highlighting must be loaded
# after executing compinit command and sourcing other plugins
zplug "zsh-users/zsh-syntax-highlighting", defer:3

# 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. 🫶

🧚 FURTHER DOCUMENTATION 🧚

See the references in the official wiki page to get started using zplug. The wiki may perhaps be overwhelming for first-time users. 😭

💀 AUTHORS 💀

zplug was originally written by Masaki Ishiyama (a.k.a @b4b4r07). Many people have contributed to it. 💖

🍓 COPYING 🍓

MIT License

🐛 REPORTING BUGS 🐛

ok so if something's acting up and it's giving broken, bestie, don't just suffer in silence — report bugs to the zplug issues 🫶

like, that's literally the move. the issues tracker is where the zplug girlies hang out and fix things, so slide in there and tell them what's wrong. no cap. ✨

and that's a wrap on the whole page, bestie 🎀 the ZPLUG Manual is dated 12/22/2016, and this whole serve lives under ZPLUG(1). go forth, plug in your zsh, and slay 💅💖✨

📦 where this page comes from

debian bookworm: zplug 2.4.2-2 · MIT
debian trixie: zplug 2.4.2-2 · MIT
nixpkgs unstable: zplug 2.4.2
ubuntu jammy: zplug 2.4.2-1 · MIT
ubuntu noble: zplug 2.4.2-2 · MIT
ubuntu resolute: zplug 2.4.2-3 · MIT
ubuntu stonking: zplug 2.4.2-3 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms