Argcomplete

Common errors

Warnings

Install

Install compatibility verified last tested: 2026-05-12

Imports

• argcomplete

  import argcomplete

• autocomplete

  from argcomplete import autocomplete

• ChoicesCompleter
  wrong

  from argcomplete import ChoicesCompleter

  correct

  from argcomplete.completers import ChoicesCompleter

  Completer classes are located in the `argcomplete.completers` submodule.

• CompletionFinder
  wrong

  from argcomplete import CompletionFinder

  correct

  from argcomplete.completion_finder import CompletionFinder

  The `CompletionFinder` class is an internal component and generally not directly imported or used by end-users. `argcomplete.autocomplete()` is the public entry point. It was also not available in older versions (e.g., < 0.8.0).

Quickstart verified last tested: 2026-04-24

Create a Python script (e.g., `my_cli.py`) with the `#!` shebang and the `# PYTHON_ARGCOMPLETE_OK` marker. Initialize your `ArgumentParser`, add arguments, and then call `argcomplete.autocomplete(parser)` before `parser.parse_args()`. To activate completion for this script in your shell, run `eval "$(register-python-argcomplete my_cli.py)"`. For global activation across all argcomplete-enabled scripts, run `activate-global-python-argcomplete` once.

#!/usr/bin/env python
# PYTHON_ARGCOMPLETE_OK
import argparse
import argcomplete

def main():
    parser = argparse.ArgumentParser(description='A simple CLI tool with completion.')
    parser.add_argument('--name', help='Your name').completer = argcomplete.completers.ChoicesCompleter(['Alice', 'Bob', 'Charlie'])
    parser.add_argument('--action', choices=['start', 'stop', 'restart'], help='Action to perform')

    # Enable argcomplete on the parser
    argcomplete.autocomplete(parser)

    args = parser.parse_args()

    if args.name:
        print(f"Hello, {args.name}!")
    if args.action:
        print(f"Performing action: {args.action}")

if __name__ == '__main__':
    main()