Manifest format#

The completion manifest (completion.msgpack) connects the Python introspection step to the Rust completion engine. It uses msgpack, a compact binary format also used in conda’s sharded repodata stack.

Location#

The manifest is stored in your platform’s cache directory:

Platform	Path
Linux	`~/.cache/conda/completion/completion.msgpack`
macOS	`~/Library/Caches/conda/completion/completion.msgpack`
Windows	`%LOCALAPPDATA%\conda\cache\completion\completion.msgpack`

Pass conda completion --cache-dir PATH or set CONDA_COMPLETION_CACHE_DIR to override the directory that contains the manifest and related cache files.

Package versions are stored in two files in the same directory: versions.index and versions.store. They are only loaded when = is detected in the current word (e.g., numpy=<TAB>).

Schema#

The manifest is a msgpack-encoded dict with these top-level keys. Shown here as equivalent JSON for readability:

{
  "version": 1,
  "generated_at": "2026-01-15T10:30:00+00:00",
  "plugin_hash": "a1b2c3d4e5f67890",
  "package_names": ["numpy", "pandas", "scipy", "..."],
  "root_options": {
    "--verbose": {"short": "-v", "description": "Increase verbosity"},
    "--json": {"description": "Report as JSON"}
  },
  "commands": {
    "install": {
      "summary": "Install a list of packages",
      "options": {
        "--name": {
          "short": "-n",
          "completion_type": "env_name",
          "description": "Name of environment",
          "metavar": "ENVIRONMENT",
          "group": "Target Environment Specification"
        },
        "--channel": {
          "short": "-c",
          "completion_type": "channel",
          "description": "Additional channel to search"
        }
      }
    }
  }
}

Field reference#

Root fields#

version: Schema version. Currently 1.
generated_at: ISO 8601 timestamp of when the manifest was generated.
plugin_hash: A hex string hashing the set of registered plugin entry point names. Used to detect when plugins have been added or removed.
package_names: Deduplicated, sorted list of all package names across configured channels when repodata is included during conda completion generate. Used for package name completion in conda install, conda remove, etc. Omitted when generation runs with --no-repodata.

CommandSpec#

summary: Help text for the command (shown in zsh/fish/PowerShell completions).
options: Map of flag names to OptionSpec objects (keyed by long form, e.g., "--name").
positionals: List of positional argument specs.
subcommands: Nested map of subcommand names to CommandSpec objects.
exclusive_groups: List of lists of mutually exclusive flag names.

OptionSpec#

short: Short flag form (e.g., "-n").
choices: List of allowed values (static completion).
nargs: Argument count ("0", "1", "?", "*", "+").
completion_type: Dynamic completion type. One of: env_name, channel, directory, package_spec, task_name, global_tool.
description: Help text for the flag.
metavar: Display name for the value (e.g., "NAME", "PATH").
default: Default value (informational).
required: Whether the flag is required.
group: Argparse action group title, when conda or a plugin provides one. The zsh integration uses it to keep related candidates together.

PositionalSpec#

name: Argument destination name.
choices: List of allowed values.
nargs: Argument count.
completion_type: Dynamic completion type (same values as OptionSpec).
description: Help text.
metavar: Display name for the value.

Version files#

The version cache uses an indexed msgpack store:

versions.index: A msgpack-encoded dict mapping package names to (offset, length) records in versions.store.
versions.store: A byte store containing one msgpack-encoded version list per package.

The completion engine only loads these files when = or == is detected in the current word (e.g., numpy=<TAB>). Normal package name completion reads only completion.msgpack.

Shown as equivalent JSON, the index looks like:

{
  "numpy": [0, 24],
  "pandas": [24, 29]
}

Each referenced store record is a msgpack-encoded list such as ["2.1.0", "2.0.0", "1.26.4"]. This avoids deserializing the full package-to-version mapping for a single version lookup while preserving the simple msgpack format.