// ZSH-PIP-DESCRIPTION-COMPLETION — REMOTE pip install COMPLETION WITH VERSION + DESCRIPTION

zsh plugin · all OMZ pip completion · plus live pip search-backed completer · menu shows package version + description

GitHub Issues
// Color scheme

>_ZSH-PIP-DESCRIPTION-COMPLETION

pip install <TAB> with version + description. All functionality of the OMZ pip completion plus a live pip search-backed completer for pip install. The descriptions in the zsh menu show the package version and short description.

Overview

This is a #compdef completion plugin for the pip command. It carries the full subcommand and flag surface of the Oh My Zsh pip completion, and adds a live remote completer: when you tab-complete a package argument to pip install (or pip search), it shells out to pip search $PREFIX, parses the result, and feeds zsh's _describe a map whose description is the package version + short description. The completion menu then shows the version and a one-line summary next to each candidate.

One #compdef line registers the completer against seven pip binary aliases — pip, pip2, pip-2.7, pip3, pip-3.2, pip-3.3, pip-3.4. A separate cache layer (zsh-pip-cache-packages) downloads the PyPI simple index (https://pypi.org/simple/) once, extracts every package name, and stores the list in ~/.pip/zsh-cache for reuse.

Install

# Zinit
zinit ice lucid nocompile
zinit load MenkeTechnologies/zsh-pip-description-completion

# Oh My Zsh
git clone https://github.com/MenkeTechnologies/zsh-pip-description-completion \
    "$HOME/.oh-my-zsh/custom/plugins/zsh-pip-description-completion"
# then: plugins+=(zsh-pip-description-completion)

# Manual
git clone https://github.com/MenkeTechnologies/zsh-pip-description-completion
source zsh-pip-description-completion/zsh-pip-description-completion.plugin.zsh

The entrypoint zsh-pip-description-completion.plugin.zsh self-locates via the ZSH_ARGZERO idiom, prepends src/ to fpath (so _pip is found by compsys), appends autoload/, and autoload -Uz's every helper in autoload/. No compinit call is made by the plugin itself — your ~/.zshrc must run compinit as usual.

Examples

pip <TAB>                # subcommand completion (install, download, freeze, ...)
pip install <TAB>        # live remote completion: menu shows version + description
pip install requests<TAB> # prefix-filtered remote candidates with version + desc
pip install -r <TAB>     # _files: complete a requirements file path
pip install -e <TAB>     # _files -/: directory-only (editable source path)
pip uninstall <TAB>      # locally installed packages (from pip freeze)
pip show <TAB>           # locally installed packages
pip search <TAB>         # live remote search candidates

For pip install, when no remote candidate is found the completer falls back to local archive files matching *.tar.gz / *.whl.

Configuration

ZSH_PIP_INDEXESArray of package-index URLs the cache builder downloads. Default (https://pypi.org/simple/). Set it in ~/.zshrc to use private/mirror indexes. A bogus index produces no error — it is silently skipped.
ZSH_PIP_CACHE_FILEPath to the cached package-name list. Default ~/.pip/zsh-cache. The parent directory is created on first use.

Helper commands

The plugin autoloads four helper functions from autoload/:

zsh-pip-cache-packagesBuilds $ZSH_PIP_CACHE_FILE if absent: downloads each $ZSH_PIP_INDEXES URL with curl -L, pipes through zsh-pip-clean-packages, then sort | uniq into a single space-separated line. Prints (...caching package index...) while it runs.
zsh-pip-clean-packagesA one-line sed filter that extracts package names from PyPI HTML <a href> anchors. Reads stdin, writes one name per line.
zsh-pip-clear-cacheRemoves $ZSH_PIP_CACHE_FILE and unsets the in-shell piplist array so the next completion rebuilds the cache. Run this when PyPI's index has changed.
zsh-pip-test-clean-packagesSelf-test for the sed extractor: feeds two known PyPI HTML fixtures (simple index + djangopypi2 form) through zsh-pip-clean-packages and reports whether the regex still matches.

Troubleshooting

  • No remote candidates appear. The live completer shells out to pip search; if your pip build returns no search output, __pip_search yields nothing and (for pip install) falls back to local *.tar.gz / *.whl file completion.
  • Stale cache. Run zsh-pip-clear-cache to delete ~/.pip/zsh-cache and force a fresh download on next tab.
  • A custom index isn't completing. A bad URL in ZSH_PIP_INDEXES is skipped without an error message — double-check the URL.

Sibling plugins

Part of the MenkeTechnologies zsh plugin family — the MenkeTechnologiesMeta umbrella: