Argcomplete

3.6.3 · active · verified Sun Mar 29

Argcomplete provides robust and extensible tab completion for command-line interfaces built with Python's `argparse` library. It enhances user experience by offering dynamic suggestions for arguments, options, and their values in shells like Bash and Zsh. The library is actively maintained with frequent releases, often including compatibility fixes for newer Python versions and shell environments.

Warnings

gotcha The `# PYTHON_ARGCOMPLETE_OK` marker must be present within the first 1024 bytes of the script file for global completion to detect it. Incorrect placement can lead to completion not working.
Fix: Ensure '# PYTHON_ARGCOMPLETE_OK' is near the top of your script file, ideally on the second line after the shebang.
gotcha Heavy computations or side effects executed before `argcomplete.autocomplete(parser)` in your script will run every time tab completion is attempted. This can make completion sluggish and unresponsive, negatively impacting user experience.
Fix: Structure your script to initialize the `ArgumentParser` and call `argcomplete.autocomplete()` as early as possible in the execution flow. Defer expensive operations until after `parser.parse_args()`.
breaking Argcomplete requires Bash 4.2+ for global completion. Older Bash versions (e.g., Bash 3.2 on macOS by default) do not support the `complete -D` functionality needed, leading to global completion failures.
Fix: Upgrade Bash to version 4.2 or newer, or use Zsh which has native support. Alternatively, register each script individually using `eval "$(register-python-argcomplete my-script.py)"`.
breaking Specific argcomplete versions were required to maintain compatibility with changes in Python's `argparse` module, particularly with Python 3.11.9+, 3.12.3+, 3.12.8+, and 3.13.1+. Failing to update could result in completion errors or broken argument parsing.
Fix: Always use the latest stable version of `argcomplete` to ensure compatibility with the most recent Python releases. Check release notes for specific compatibility updates.
gotcha If your script tries to read from `stdin` during completion, it can cause the shell to lock up, as `argcomplete` typically redirects `stdin` during completion generation. This was explicitly addressed in v3.4.0.
Fix: Upgrade to argcomplete 3.4.0 or newer. Ensure your completion logic (code executed before `parse_args()` when `argcomplete` is active) does not attempt to read from `stdin`.
gotcha After debugging completion issues or if an older completion function was registered, the shell might retain a broken completion. This can manifest as `_minimal` being used or no completion at all.
Fix: Restart your shell, or run `complete -r my-python-app` to remove a specific completion, or `complete -r -D` to remove the default completion (if set by `activate-global-python-argcomplete`). Setting `_ARC_DEBUG=1` can help diagnose issues.

Install

pip install argcomplete Install library
activate-global-python-argcomplete Activate global completion (Bash/Zsh)
eval "$(register-python-argcomplete my-script.py)" Register a single script (Bash/Zsh)

Imports

argcomplete
```
import argcomplete
```
autocomplete
```
from argcomplete import autocomplete
```
ChoicesCompleter
```
from argcomplete.completers import ChoicesCompleter
```
Completer classes are located in the `argcomplete.completers` submodule.
CompletionFinder
```
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

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()

view raw JSON →