Install & Compatibility
Where this runs
tested against v3.7.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.036s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.034s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
argcomplete
✓ import argcomplete
autocomplete
✓ from argcomplete import autocomplete
ChoicesCompleter
✓ from argcomplete.completers import ChoicesCompleter
✗ from argcomplete import ChoicesCompleter
Completer classes are located in the `argcomplete.completers` submodule.
CompletionFinder
✓ from argcomplete.completion_finder import CompletionFinder
✗ from argcomplete 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).
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()
register-python-argcomplete --version
Debug
Known issues
gotchaThe `# 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.fixEnsure '# PYTHON_ARGCOMPLETE_OK' is near the top of your script file, ideally on the second line after the shebang.
affects: All versions
gotchaHeavy 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.fixStructure 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()`.
affects: All versions
breakingArgcomplete 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.fixUpgrade 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)"`.
affects: All versions on Bash < 4.2
breakingSpecific 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.fixAlways use the latest stable version of `argcomplete` to ensure compatibility with the most recent Python releases. Check release notes for specific compatibility updates.
affects: <3.3.0 for Python 3.11.9+/3.12.3+; <3.5.2 for Python 3.12.8+/3.13.1+
gotchaIf 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.fixUpgrade 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`.
affects: <3.4.0, or scripts with problematic `stdin` access during completion calls.
gotchaAfter 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.fixRestart 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.
affects: All versions
gotchaRunning `pip` as the 'root' user, especially within containerized or automated testing environments, can lead to package permission issues, conflicts with system package managers, and an unstable environment. While not directly an `argcomplete` bug, such `pip` warnings signal an unrecommended setup that could indirectly impact `argcomplete`'s installation, dependencies, or overall script execution.fixAlways prefer using virtual environments (e.g., `venv`) for `pip` operations to isolate dependencies and avoid system conflicts. If a virtual environment is not an option, ensure `pip` commands are executed by a non-root user. Additionally, keep `pip` updated (`pip install --upgrade pip`) to benefit from the latest features and bug fixes.
affects: All versions of Python/pip when `pip` is run as root, irrespective of `argcomplete` version.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'argcomplete'
The 'argcomplete' package is not installed in the current Python environment.
fixInstall the package using pip: 'pip install argcomplete'.
AttributeError: 'Namespace' object has no attribute 'x'
Attempting to access a command-line argument that was not defined in the ArgumentParser.
fixEnsure the argument is added to the parser: 'parser.add_argument('--x', ...)' and access it as 'args.x'. AttributeError: 'Namespace' object has no attribute 'accumulate'
Accessing an attribute that was not defined due to missing or incorrect argument definitions.
fixDefine the argument with the correct 'dest' parameter: 'parser.add_argument('--sum', dest='accumulate', ...)' and access it as 'args.accumulate'. AttributeError: 'Namespace' object has no attribute 'check'
Using a different attribute name than specified in the 'dest' parameter of add_argument.
fixAccess the attribute using the name specified in 'dest': 'args.performance' if 'parser.add_argument('--check', dest='performance', ...)' was used. AttributeError: 'Namespace' object has no attribute 'command'
Accessing a subcommand argument without setting the 'dest' parameter in add_subparsers.
fixSet the 'dest' parameter when adding subparsers: 'subparsers = parser.add_subparsers(dest='command')' and access it as 'args.command'.
Upgrade
Version history
3.7.2latest on PyPI · released Aug 6, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9+ for full functionality and support.