Every instruction points at src/, and zcompdump is the trap

It is a staging ground, and scripts move upstream from it

The project describes itself in five words as additional completion definitions for Zsh, and then explains its reason for existing in one sentence that is worth reading slowly.

This project aims at gathering and developing new completion scripts that are not available in Zsh yet. The scripts may be contributed to the Zsh project when stable enough.

So the repository is not competing with Zsh's own completion functions. It is a queue. A script lands here because Zsh does not have it yet, and it leaves here when it has been good enough to be merged into Zsh itself.

That framing explains the shape of everything else on the page. There is no configuration dialect to learn, because a completion definition is a Zsh completion function and nothing more. There is no plugin API, because the integration point is Zsh's own fpath mechanism. And the contribution guidance is a link to a CONTRIBUTING file rather than a paragraph, because the project is asking for functions written the way Zsh writes them.

It also sets the right expectation about maturity. A definition here is not a Zsh release, and the direction of travel is upstream rather than sideways.

Every route ends with the src directory on fpath

There are four installation routes in this README and three of them are variations on one mechanism.

The manual route is the clearest. Clone the repository, then add a directory to fpath in your ~/.zshrc:

fpath=(path/to/zsh-completions/src $fpath)

Then run compinit. And a fourth line covers the failure case everybody hits once:

rm -f ~/.zcompdump; compinit

The README phrases that last step as something you may have to force, and it is the step people forget. Zsh caches the completion functions it has already found in ~/.zcompdump, so dropping a new file into a directory on fpath changes nothing until that cache is rebuilt.

Note which directory the line names. It is src, not the repository root. Both routes in this README that show an fpath line, manual and oh-my-zsh, use the same src subdirectory, because that is where the repository keeps its completion functions.

So the project is a directory you point fpath at, not a plugin you source. That single distinction is what the rest of the page is explaining.

oh-my-zsh users are told not to load it as a plugin

The longest section in this README is a warning, and it is specific to one plugin manager.

It says: to avoid issues with redundant .zcompdump cache generation, do not load zsh-completions as a standard plugin, and it links the issue number. Instead there is an optimized approach.

The optimized approach is to clone the repository into your custom plugins directory:

git clone https://github.com/zsh-users/zsh-completions.git \
  ${ZSH_CUSTOM:-${ZSH:-~/.oh-my-zsh}/custom}/plugins/zsh-completions

then update ~/.zshrc before sourcing oh-my-zsh:

fpath+=${ZSH_CUSTOM:-${ZSH:-~/.oh-my-zsh}/custom}/plugins/zsh-completions/src
autoload -U compinit && compinit
source "$ZSH/oh-my-zsh.sh"

And the reason is stated at the end: this prevents compinit from being called twice and significantly improves shell startup time.

So the failure being avoided is not cosmetic. oh-my-zsh calls compinit itself, and the plugin path would add a second call, and a second call means a second zcompdump. Every new shell then pays for building a cache twice. For a user with a slow login shell that is the difference between noticing and not.

The nested expansion is a rename with a fallback

One detail in those two commands is worth pulling out, because it is the kind of thing that gets copied without being understood.

The path is written as ${ZSH_CUSTOM:-${ZSH:-~/.oh-my-zsh}/custom}. That is a parameter expansion inside a parameter expansion, and each layer is a fallback.

The outer one tests ZSH_CUSTOM. If that variable is set and non-empty, its value is used. If it is not, the inner expansion runs, which tests ZSH, and if ZSH is set its custom subdirectory is used instead. Only if both are unset does it fall back to ~/.oh-my-zsh/custom.

So the expression prefers an explicit custom directory and otherwise derives one from the oh-my-zsh install location.

The other thing the lines reveal is ordering. fpath is appended to rather than assigned, compinit is called explicitly, and only then is oh-my-zsh sourced. Get that order wrong and oh-my-zsh's own compinit runs first, which is the double call the section exists to prevent.

Twelve distributions, and three of them share one repository

The package table has eleven rows, and it is arranged by distribution family rather than alphabetically.

Three rows point at the same place: Debian and Ubuntu, Fedora with CentOS, RHEL and Scientific Linux, and openSUSE with SLE all resolve to a single zsh-completions OBS repository on software.opensuse.org. That is the openSUSE build service, which is why a Debian user and a SUSE user are given the same download link.

Then one row each for the rest. Arch Linux, listed together with Manjaro, Antergos and Hyperbola, offers both a repository package and an AUR package tracking git. Gentoo and Funtoo have app-shells/zsh-completions. NixOS, Void Linux and Slackware have their own. macOS has Homebrew and MacPorts. NetBSD has pkgsrc and FreeBSD has a freshports shells/zsh-completions entry.

What the table does not say is the version in any of them, and that matters because this project releases infrequently. The three newest tags are 0.36.0 from 2026-03-09, 0.35.0 from 2023-08-30 and 0.34.0 from 2022-07-02, and the last push was on 2026-10-16.

So a distribution package may be sitting on a definition set from years ago while the branch has moved. The table tells you where to get it, not how current it is.

The licence is per file header, not one repository licence

The licence section is two sentences and the second one points at a file.

Completions use the Zsh licence, unless explicitly mentioned in the file header. See LICENSE for more information.

That is a different arrangement from most repositories, where one licence at the root covers everything. Here the default is the Zsh licence and a file can opt out by saying so in its own header, which means anyone reading the tree has to read headers to know what they are shipping.

The repository's own licence field, meanwhile, records no identifier at all, so a tool scanning this project for an SPDX value finds nothing to resolve.

The practical advice is the obvious one: check the header of the specific completion function you are about to vendor, rather than assuming the root licence settles it.

Two other root files describe the project rather than ship it. There is a zsh-completions-howto.org, a how-to document, and there is a zsh-completions.plugin.zsh, a plugin loader file. That second one is worth a second look against the section above, since the README tells oh-my-zsh users not to load the repository as a plugin.

Editorial conclusion

Take zsh-completions if you use Zsh and your distribution's package lags the commands you actually run, and you want completion definitions upstream Zsh has not shipped. Leave it if your Zsh is recent enough to already carry them, because the project's own stated purpose is the gap between what exists upstream and what people need. Verify three things. Point fpath at the src directory and not at the repository root, because both README routes that show an fpath line use that path. Run compinit once, since the oh-my-zsh instructions exist specifically to prevent a second call, and force a rebuild with rm -f ~/.zcompdump followed by compinit when definitions do not appear. And read the licence per file rather than for the repository, because the README says completions use the Zsh licence unless the file header says otherwise.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. zsh-users/zsh-completions on GitHub