Skip to main content

Automagic shell tab completion for Python CLI applications

Project description



Downloads Tests Coverage PyPI conda-forge

  • 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,tcsh}

    • subparser mode: end-users execute your_cli_app completion {bash,zsh,tcsh}


See the docs for usage examples.


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.


Project details

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.6.5.tar.gz (45.8 kB view hashes)

Uploaded source

Built Distribution

shtab-1.6.5-py3-none-any.whl (13.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page