conda-completion

Fast shell tab completion for conda and all its plugins.

A hybrid Python/Rust conda plugin that introspects conda's argparse tree (including all plugin subcommands) and provides instant TAB completions via a tiny Rust binary.

Features

• Completes all conda commands, flags, and plugin subcommands
• Package name completion from repodata (conda install nump<TAB>)
• Version completion (conda install numpy=<TAB> lists available versions)
• Fuzzy matching for typos (numpie or nupmy suggest numpy)
• Contextual completions: environment names, task names, channels from project files (conda.toml, pixi.toml, pyproject.toml, environment.yml, anaconda-project.yml, conda-project.yml, lockfiles)
• Static value completion for conda configuration keys and health checks
• Descriptions shown alongside candidates (zsh, fish, PowerShell)
• Fast response time (stat-cached context, no Python on the hot path)
• Shell support: bash, zsh, PowerShell, and fish (covered by automated tests)
• Auto-regenerates the completion manifest when plugins are installed or removed

Status

This project is in early development and available from conda-forge.

Quick start (development)

# Clone and set up
git clone https://github.com/conda-incubator/conda-completion
cd conda-completion
pixi install
pixi run build

# Generate the completion manifest
conda completion generate

# Install the shell hook (auto-detects your shell)
conda completion install

# Or target a specific shell
conda completion install bash

# Or use eval directly in your RC file
eval "$(conda completion init bash)"

How it works

conda-completion splits the work into two phases:

Phase 1: Generation (Python, runs once). conda completion generate calls conda's generate_parser(), which loads all registered plugin subcommands. The argparse tree is walked recursively to extract commands, flags, positional arguments, help text, and package names from repodata. The output is a completion.msgpack manifest plus versions.index and versions.store package-version files in the platform cache directory.

Phase 2: Completion (Rust, runs on every TAB). When you press TAB, your shell calls _conda_completer, a small Rust binary (~1 MB). It reads the msgpack manifest for static command/flag/package completions, then walks project files in your working directory for dynamic completions (environment names, task names, channels). No Python runs on the hot path. Package names are matched using a three-tier strategy (prefix, substring, then fuzzy similarity) so typos like numpie still find numpy.

A stat-based file cache tracks (mtime, size) for every source file. If nothing changed since the last TAB press, the binary skips all parsing and serves cached results directly.

What files are read

Project files (walks upward from cwd, first match wins):

Global state (always read):

CLI commands

install and uninstall support --dry-run to preview changes and --yes to skip confirmation.

generate and install support --no-repodata to skip package metadata. Use conda completion refresh to force a repodata refresh.

install, init, and uninstall support --command-name for wrapper executables, and CONDA_COMPLETION_COMMAND_NAME provides the same value from the environment.

Development

pixi install
pixi run build       # build Rust binary (release)
pixi run build-debug # build Rust binary (debug)
pixi run test        # run Python + Rust integration tests
pixi run check       # lint + format + typecheck + clippy

See RELEASING.md for the release process.

License

BSD-3-Clause