zsh-completions: extra tab-completion definitions for Zsh, and how to load them without breaking compinit

What zsh-completions adds that stock Zsh does not

Zsh's completion system is a framework. It knows how to complete arguments, files, options and subcommands, but it only knows the commands somebody wrote a definition for. The definitions for many tools live upstream in Zsh itself, and the rest have to come from somewhere. zsh-completions is that somewhere: the README describes it as a project that gathers and develops completion scripts not available in Zsh yet, with the stated intent that scripts may be contributed to the Zsh project once they are stable enough.

The audience is narrow and specific. You already use Zsh, you already run compinit, and you have noticed that tab after a command name produces nothing useful for a particular tool. This project does not change how completion works and does not touch your prompt, history or key bindings. It only puts more definition files where compinit will find them. If your problem is that completion is slow, or that you want suggestions as you type rather than on tab, this is the wrong repository.

The mechanism is fpath, not a runtime

There is no daemon and no hook. Zsh resolves completion definitions by searching the directories listed in the fpath array for a file named after the command, conventionally prefixed with an underscore. Adding the repository's src directory to fpath is the whole integration. compinit then scans those directories at startup and builds a dump file, usually ~/.zcompdump, that caches what it found so the next shell start is faster.

That cache is the source of most confusion. If you add a directory to fpath after compinit has already built the dump, the new definitions are not in the cache and tab still does nothing. The README's manual instructions end with a step that deletes the dump and reruns compinit, which is the honest way to describe the situation: the change is only visible after the cache is rebuilt. The repository layout matches this design. The completion files sit under src/, and the top level also carries a plugin file, zsh-completions.plugin.zsh, which exists so plugin managers have something to source. The definitions themselves are still the point.

Installing zsh-completions and completing your first command

The README lists packages for a long set of systems, including Debian and Ubuntu through an OBS repository, Fedora and its relatives, Arch, Gentoo, NixOS, Void, Slackware, macOS through Homebrew and MacPorts, NetBSD and FreeBSD. If your system has a package, prefer it, because the package manager decides where the files land and keeps them updated. The manual route is a clone plus an fpath entry.

Clone the repository first:

git clone https://github.com/zsh-users/zsh-completions.git

Then point fpath at the src directory. The README gives this form for ~/.zshrc, with the placeholder path replaced by wherever you cloned it:

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

Order matters here. The new directory is prepended, so its definitions are searched before anything already on fpath. After that, rebuild the completion dump and restart the shell:

rm -f ~/.zcompdump; compinit

What you should see is that tab after a command name now offers subcommands and flags that previously produced nothing. If it does not, the two things to check are whether compinit ran after the fpath change and whether the file for that command is actually present in src.

The oh-my-zsh path is deliberately not a plugin load

Most oh-my-zsh plugins are named in the plugins array. The README tells you not to do that here, citing redundant .zcompdump cache generation in issue 603. The recommended approach is a clone into the custom plugins directory followed by an fpath entry and an explicit compinit, both placed before oh-my-zsh itself is sourced.

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

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

The README's stated reason is that this prevents compinit from being called twice and improves shell startup time. That is a real trade-off rather than a style preference: you give up the convenience of a one-line plugin entry in exchange for control over when the completion cache is built. Anyone copying the plugin name into the plugins array anyway is working against the project's own instructions. For antigen the README gives a single bundle line, and for zinit a single light line.

Where zsh-completions will not help you

The project adds definitions. It does not add suggestions. Searching for zsh completions versus autosuggestions lands on a distinction the README never makes, because the two do different jobs: completion is what appears when you press tab, while autosuggestions draw a greyed-out guess from your history as you type. Installing zsh-completions will not produce inline suggestions, and installing an autosuggestion plugin will not teach Zsh the flags of a new command.

A second limit is coverage. The README's framing is that scripts are collected and may later be contributed upstream when stable enough, which means the set is neither complete nor uniform in quality. A command you use daily may simply not be represented in src, and no amount of configuration fixes that. The third limit is the cache behaviour described above. On a machine where the dump file is managed by a framework or a dotfile tool, deleting ~/.zcompdump and rerunning compinit by hand can conflict with whatever else expects to own that file.

How it differs from zsh-autocomplete and from shipping completions upstream

The related searches put zsh-completions against zsh-autocomplete, and the difference is architectural. zsh-autocomplete is a completion interface: it changes when and how candidates are presented, including menu-style behaviour as you type. zsh-completions is a data package. You can run both, and they do not overlap in responsibility, but only one of them is what you want if the complaint is that your shell never guesses what you mean.

The other comparison is with Zsh itself. The README states the project's aim is to gather scripts that are not in Zsh yet and to contribute them upstream when stable. That makes zsh-completions partly a staging area. A definition you rely on today may end up in a future Zsh release, at which point the package is redundant for that command but still carries everything else. The practical consequence is that keeping it installed costs you an fpath entry and a directory of shell files, not a running process.

Maintenance, packaging and the licence question

The repository is not archived, and the last push was on 2026-09-21, one day before this writing, so activity is current. Releases are infrequent by design: 0.36.0 on 2026-03-09, 0.35.0 on 2023-08-30, and 0.34.0 on 2022-07-02. A completion definition does not need a release cadence to work, but it does mean that if you install from a distro package rather than from git, you may be running definitions that are years behind the master branch. Arch users have both a stable package and a git variant, which makes the choice explicit.

On licensing, the README states that completions use the Zsh license unless a file header says otherwise, and points at the LICENSE file for details. The repository metadata reports the licence as NOASSERTION, so tooling that reads licence fields may not classify it automatically. If you redistribute the definitions inside a product, read the per-file headers rather than trusting a single top-level label. This is a description of what the files say, not legal advice.

Editorial conclusion

Adopt zsh-completions if you already run Zsh and keep hitting commands whose flags you have to look up. Skip it if your distro package already ships a completions directory, or if you expect a plugin that changes how completion behaves rather than one that only adds definitions. Before relying on it, check that the directory you add to fpath actually contains the file for the command you care about, and confirm where the package manager put it rather than assuming the README's source path.

Frequently asked questions

Official sources

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