Diagnose and repair completion problems#

Use this guide when completion is installed but the behavior does not match what you expect.

Start with status#

Run status in the same terminal where completion is failing:

conda completion status

Save the output while debugging. It shows the cache directory, manifest path, manifest age, package metadata files, plugin hash, current plugin hash, and completer binary path.

Check whether the shell hook is loaded#

If pressing TAB behaves exactly like ordinary file completion, the shell probably did not load the conda-completion hook.

Preview where the hook would be installed:

conda completion install --dry-run

Then install for the shell you are actually using. For example:

conda completion install zsh

Use bash, zsh, powershell, or fish as the shell argument.

Restart the terminal after installation. If you cannot restart it, source the file named by the installer.

For custom startup layouts, use Install in nonstandard shell startup files.

Confirm that conda is available at shell startup#

The installed hook is guarded so it only runs when conda is available on PATH. If completions work after activating an environment but not in a fresh terminal, initialize conda for that shell first:

conda init

Restart the shell, then run:

conda completion install

Place any manual conda-completion hook after the block created by conda init.

Regenerate stale command data#

Run:

conda completion generate

This refreshes command, flag, plugin, and argparse metadata. It reuses package metadata when the package cache is still fresh.

If conda completion status shows different Plugin hash and Current plugin hash values, command data was generated with a different plugin set. generate rewrites the manifest with the current plugin hash.

Refresh stale package data#

If command completions work but a package or version is missing, refresh repodata:

conda completion refresh

If the cache was created with --no-repodata, package name and version candidates are absent by design. Run conda completion generate without --no-repodata to add them.

Remove corrupt cache files#

If status or completion reports that it cannot read completion data, remove the generated files and regenerate them.

rm -f ~/.cache/conda/completion/completion.msgpack
rm -f ~/.cache/conda/completion/versions.index
rm -f ~/.cache/conda/completion/versions.store
conda completion generate

rm -f ~/Library/Caches/conda/completion/completion.msgpack
rm -f ~/Library/Caches/conda/completion/versions.index
rm -f ~/Library/Caches/conda/completion/versions.store
conda completion generate

Remove-Item "$env:LOCALAPPDATA\conda\cache\completion\completion.msgpack" -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\conda\cache\completion\versions.index" -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\conda\cache\completion\versions.store" -ErrorAction SilentlyContinue
conda completion generate

The context cache file can also be removed safely. It is rebuilt on the next TAB press:

rm -f ~/.cache/conda/completion/context_cache.msgpack

Use the cache directory printed by conda completion status when it differs from these defaults.

Fix a missing completer binary#

If status says the completion engine binary is missing, install the runtime package into the environment that provides conda completion:

conda install -c conda-forge conda-completer

Then regenerate:

conda completion generate

If you pasted the full output of conda completion init into a startup file, it may contain an old binary path. Replace it with the shorter eval hook from Install in nonstandard shell startup files, or regenerate the pasted script from the environment you use now.

Investigate slow TAB presses#

Tab completion should normally complete quickly after the first run in a directory. If it remains slow:

  • Run conda completion status and confirm the manifest exists.

  • Remove context_cache.msgpack so project file context is rebuilt.

  • Check whether the current directory is on NFS, SSHFS, FUSE, or a slow cloud-synced filesystem.

  • Try from a shallow directory. The completer walks upward looking for project files and stops at VCS roots.

  • Use conda completion generate --no-repodata in constrained CI or container builds where package candidates are not needed.

Collect useful issue details#

When opening an issue, include:

  • Output from conda completion status.

  • Shell name and version.

  • Operating system.

  • The exact command line where TAB behaves incorrectly.

  • Whether the manifest was generated with --no-repodata.

  • Any project files involved, with private names redacted if needed.

On this page
Show Source