Registry / devops / shtab
library1.12.0pypypi✓ verified 24d ago

shtab is a Python library that automatically generates shell tab completion scripts for command-line interface (CLI) applications. It processes an `argparse.ArgumentParser` object to produce completion scripts for `bash`, `zsh`, and `tcsh`. It aims for speed and correctness, avoiding the side-effects and performance issues of alternatives like `argcomplete` and `pyzshcomplete`. As of version 1.8.0, it is actively maintained by Iterative AI, with its development often driven by the needs of projects like DVC, but designed for general-purpose use.

pip install shtab
INSTALL
IMPORT
SIG · SHTAB
S
shtab
devopspythonv1.12.0
Install
1.6s avg
Import
127ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.12.0 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.132s · 17.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.122s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

complete
from shtab import complete
import shtab; shtab.complete(...)

This quickstart demonstrates how to integrate `shtab` into an `argparse`-based CLI application. By calling `shtab.add_argument(parser)`, a hidden argument (e.g., `--print-completion`) is added to your parser, allowing users to generate completion scripts for their shell. Users would then run `python your_script.py --print-completion bash` to get the script and install it according to their shell's instructions (e.g., sourcing it in their `.bashrc`). The example includes common argparse features like choices and environment variable defaults.

import argparse import shtab import os def get_main_parser(): parser = argparse.ArgumentParser(prog='mycli', description='A simple CLI tool') parser.add_argument('--auth-key', type=str, default=os.environ.get('MYCLI_AUTH_KEY', ''), help='Authentication key') parser.add_argument('--output', '-o', choices=['json', 'yaml', 'text'], default='text', help='Output format') parser.add_argument('command', choices=['status', 'run', 'config'], help='Command to execute') return parser if __name__ == '__main__': parser = get_main_parser() # Integrate shtab for completion. This creates a hidden argument like --print-completion shtab.add_argument(parser, shells=['bash', 'zsh', 'tcsh']) args = parser.parse_args() # Example of how a user would generate and install completion: # mycli --print-completion bash > ~/.bashrc.d/mycli.bash-completion # source ~/.bashrc.d/mycli.bash-completion print(f"Running command: {args.command}") if args.auth_key: print("Auth key provided.") else: print("No auth key provided.") print(f"Output format: {args.output}")
shtab --version
Debug
Known issues
gotchaShell environment setup is crucial. Users must ensure their shell (e.g., bash, zsh) is configured to source completion scripts, and the `shtab`-generated script is placed in a directory where the shell looks for completions (e.g., `~/.bashrc.d/`, `$fpath` for zsh). In addition, both `shtab` and the application it's completing must be accessible/importable from the environment where the completion script is generated and used.
fix
Refer to `shtab` documentation for OS-specific installation steps for bash-completion or zsh completion. Ensure your shell config (`.bashrc`, `.zshrc`) properly sources completion files and that the generated script is in the correct location. Verify `shtab` and your application are in `PATH` and `PYTHONPATH` if necessary.
affects: All versions
gotchaBy default, `shtab` may silently fail if it cannot import the requested application's parser object. This can lead to confusion if completion isn't working as expected without any error messages. Additionally, the `prog` argument of `argparse.ArgumentParser` must accurately reflect the executable's name for correct completion, especially when using `options.entry_points.console_scripts` or direct script execution.
fix
When using `shtab` from the CLI, add the `--error-unimportable` flag to get explicit error messages if the parser cannot be imported. Always ensure `argparse.ArgumentParser(prog="YOUR_CLI_NAME")` matches the name users will type, or use `shtab --prog=YOUR_CLI_NAME ...` to override it.
affects: All versions
Upgrade
Version history
1.12.0latest on PyPI · released Aug 24, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.
Agent activity
23 hits · last 30 days
node
18
OpenAI (training)
1
Resources
shtab — pip install shtab · libregistry