Skip to main content

Automagic shell tab completion for Python CLI applications

Project description



Tests Coverage conda-forge PyPI

  • What: Automatically generate shell tab completion scripts for Python CLI apps
  • Why: Speed & correctness. Alternatives like argcomplete and pyzshcomplete are slow and have side-effects
  • How: shtab processes an argparse.ArgumentParser object to generate a tab completion script for your shell


  • Outputs tab completion scripts for
    • bash
    • zsh
    • tcsh
  • Supports
  • Supports arguments, options and subparsers
  • Supports choices (e.g. --say={hello,goodbye})
  • Supports file and directory path completion
  • Supports custom path completion (e.g. --file={*.txt})


Choose one of:

  • pip install shtab, or
  • conda install -c conda-forge shtab

See operating system-specific instructions in the docs.


There are two ways of using shtab:

  • CLI Usage: shtab’s own CLI interface for external applications
    • may not require any code modifications whatsoever
    • end-users execute shtab your_cli_app.your_parser_object
  • Library Usage: as a library integrated into your CLI application
    • adds a couple of lines to your application
    • argument mode: end-users execute your_cli_app --print-completion {bash,zsh}
    • subparser mode: end-users execute your_cli_app completion {bash,zsh}


Not working? Check out frequently asked questions.


  • argcomplete
    • executes the underlying script every time <TAB> is pressed (slow and has side-effects)
    • only provides bash completion
  • pyzshcomplete
    • executes the underlying script every time <TAB> is pressed (slow and has side-effects)
    • only provides zsh completion
  • click
    • different framework completely replacing the builtin argparse
    • solves multiple problems (rather than POSIX-style “do one thing well”)


Please do open issues & pull requests! Some ideas:

  • support fish
  • support powershell

See for more guidance.


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

shtab-1.5.4.tar.gz (45.3 kB view hashes)

Uploaded source

Built Distribution

shtab-1.5.4-py2.py3-none-any.whl (13.5 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page