Python and tab completion, better together.
Alternatives To Argcomplete
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
a month ago1February 27, 2018103wtfplShell
z - jump around
Zsh Autocomplete3,372
7 hours ago6mitShell
🤖 Real-time type-ahead completion for Zsh. Asynchronous find-as-you-type autocompletion.
Fzf Tab2,055
2 months ago57mitShell
Replace zsh's default completion selection menu with fzf!
Bash Sensible1,907
9 months ago10mitShell
An attempt at saner Bash defaults
Argcomplete1,2111,4124173 days ago101January 03, 202254apache-2.0Python
Python and tab completion, better together.
17 days ago17mitC
Yori is a CMD replacement shell that supports backquotes, job control, and improves tab completion, file matching, aliases, command history, and more.
Gradle Completion935
2 months ago54mitShell
Gradle tab completion for bash and zsh
a year ago26mitShell
Ef-🐟-ient fish keybindings for fzf
Docopt.rs7241,4543532 years ago87March 12, 202149otherRust
Docopt for Rust (command line argument parser).
Cmd253341694a month ago127April 13, 202215mitPython
cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
Alternatives To Argcomplete
Select To Compare

Alternative Project Comparisons

argcomplete - Bash/zsh tab completion for argparse

Tab complete all the things!

Argcomplete provides easy, extensible command line tab completion of arguments for your Python application.

It makes two assumptions:

  • You're using bash or zsh as your shell
  • You're using argparse to manage your command line arguments/options

Argcomplete is particularly useful if your program has lots of options or subparsers, and if your program can dynamically suggest completions for your argument/option values (for example, if the user is browsing resources over the network).


pip install argcomplete

On Linux, you will need to run the second command with sudo. See Activating global completion below for details.

Refresh your shell environment (start a new shell).


Add the PYTHON_ARGCOMPLETE_OK marker and a call to argcomplete.autocomplete() to your Python application as follows:

#!/usr/bin/env python
import argcomplete, argparse
parser = argparse.ArgumentParser()
args = parser.parse_args()

Register your Python application with your shell's completion framework by running register-python-argcomplete:

eval "$(register-python-argcomplete my-python-app)"

Quotes are significant; the registration will fail without them. See Global completion below for a way to enable argcomplete generally without registering each application individually.


This method is the entry point to the module. It must be called after ArgumentParser construction is complete, but before the ArgumentParser.parse_args() method is called. The method looks for an environment variable that the completion hook shellcode sets, and if it's there, collects completions, prints them to the output stream (fd 8 by default), and exits. Otherwise, it returns to the caller immediately.

Side effects

Argcomplete gets completions by running your program. It intercepts the execution flow at the moment argcomplete.autocomplete() is called. After sending completions, it exits using exit_method (os._exit by default). This means if your program has any side effects that happen before argcomplete is called, those side effects will happen every time the user presses <TAB> (although anything your program prints to stdout or stderr will be suppressed). For this reason it's best to construct the argument parser and call argcomplete.autocomplete() as early as possible in your execution flow.


If the program takes a long time to get to the point where argcomplete.autocomplete() is called, the tab completion process will feel sluggish, and the user may lose confidence in it. So it's also important to minimize the startup time of the program up to that point (for example, by deferring initialization or importing of large modules until after parsing options).

Specifying completers

You can specify custom completion functions for your options and arguments. Two styles are supported: callable and readline-style. Callable completers are simpler. They are called with the following keyword arguments:

  • prefix: The prefix text of the last word before the cursor on the command line. For dynamic completers, this can be used to reduce the work required to generate possible completions.
  • action: The argparse.Action instance that this completer was called for.
  • parser: The argparse.ArgumentParser instance that the action was taken by.
  • parsed_args: The result of argument parsing so far (the argparse.Namespace args object normally returned by ArgumentParser.parse_args()).

Completers can return their completions as an iterable of strings or a mapping (dict) of strings to their descriptions (zsh will display the descriptions as context help alongside completions). An example completer for names of environment variables might look like this:

def EnvironCompleter(**kwargs):
    return os.environ

To specify a completer for an argument or option, set the completer attribute of its associated action. An easy way to do this at definition time is:

from argcomplete.completers import EnvironCompleter

parser = argparse.ArgumentParser()
parser.add_argument("--env-var1").completer = EnvironCompleter
parser.add_argument("--env-var2").completer = EnvironCompleter

If you specify the choices keyword for an argparse option or argument (and don't specify a completer), it will be used for completions.

A completer that is initialized with a set of all possible choices of values for its action might look like this:

class ChoicesCompleter(object):
    def __init__(self, choices):
        self.choices = choices

    def __call__(self, **kwargs):
        return self.choices

The following two ways to specify a static set of choices are equivalent for completion purposes:

from argcomplete.completers import ChoicesCompleter

parser.add_argument("--protocol", choices=('http', 'https', 'ssh', 'rsync', 'wss'))
parser.add_argument("--proto").completer=ChoicesCompleter(('http', 'https', 'ssh', 'rsync', 'wss'))

Note that if you use the choices=<completions> option, argparse will show all these choices in the --help output by default. To prevent this, set metavar (like parser.add_argument("--protocol", metavar="PROTOCOL", choices=('http', 'https', 'ssh', 'rsync', 'wss'))).

The following script uses parsed_args and Requests to query GitHub for publicly known members of an organization and complete their names, then prints the member description:

#!/usr/bin/env python
import argcomplete, argparse, requests, pprint

def github_org_members(prefix, parsed_args, **kwargs):
    resource = "{org}/members".format(org=parsed_args.organization)
    return (member['login'] for member in requests.get(resource).json() if member['login'].startswith(prefix))

parser = argparse.ArgumentParser()
parser.add_argument("--organization", help="GitHub organization")
parser.add_argument("--member", help="GitHub member").completer = github_org_members

args = parser.parse_args()


Try it like this:

./ --organization heroku --member <TAB>

If you have a useful completer to add to the completer library, send a pull request!

Readline-style completers

The readline module defines a completer protocol in rlcompleter. Readline-style completers are also supported by argcomplete, so you can use the same completer object both in an interactive readline-powered shell and on the command line. For example, you can use the readline-style completer provided by IPython to get introspective completions like you would get in the IPython shell:

import IPython
parser.add_argument("--python-name").completer = IPython.core.completer.Completer()

argcomplete.CompletionFinder.rl_complete can also be used to plug in an argparse parser as a readline completer.

Printing warnings in completers

Normal stdout/stderr output is suspended when argcomplete runs. Sometimes, though, when the user presses <TAB>, it's appropriate to print information about why completions generation failed. To do this, use warn:

from argcomplete import warn

def AwesomeWebServiceCompleter(prefix, **kwargs):
    if login_failed:
        warn("Please log in to Awesome Web Service to use autocompletion")
    return completions

Using a custom completion validator

By default, argcomplete validates your completions by checking if they start with the prefix given to the completer. You can override this validation check by supplying the validator keyword to argcomplete.autocomplete():

def my_validator(completion_candidate, current_input):
    """Complete non-prefix substring matches."""
    return current_input in completion_candidate

argcomplete.autocomplete(parser, validator=my_validator)

Global completion

In global completion mode, you don't have to register each argcomplete-capable executable separately. Instead, the shell will look for the string PYTHON_ARGCOMPLETE_OK in the first 1024 bytes of any executable that it's running completion for, and if it's found, follow the rest of the argcomplete protocol as described above.

Additionally, completion is activated for scripts run as python <script> and python -m <module>. This also works for alternate Python versions (e.g. python3 and pypy), as long as that version of Python has argcomplete installed.

Bash version compatibility

When using bash, global completion requires bash support for complete -D, which was introduced in bash 4.2. Since Mac OS ships with an outdated version of Bash (3.2), you can either use zsh or install a newer version of bash using Homebrew (brew install bash - you will also need to add /usr/local/bin/bash to /etc/shells, and run chsh to change your shell). You can check the version of the running copy of bash with echo $BASH_VERSION.


If you use setuptools/distribute scripts or entry_points directives to package your module, argcomplete will follow the wrapper scripts to their destination and look for PYTHON_ARGCOMPLETE_OK in the destination code.

If you choose not to use global completion, or ship a completion module that depends on argcomplete, you must register your script explicitly using eval "$(register-python-argcomplete my-python-app)". Standard completion module registration roules apply: namely, the script name is passed directly to complete, meaning it is only tab completed when invoked exactly as it was registered. In the above example, my-python-app must be on the path, and the user must be attempting to complete it by that name. The above line alone would not allow you to complete ./my-python-app, or /path/to/my-python-app.

Activating global completion

The script activate-global-python-argcomplete will try to install the global completion script bash_completion.d/python-argcomplete (see on GitHub) into an appropriate location on your system for both bash and zsh (/etc/bash_completion.d and /usr/local/share/zsh/site-functions). On Linux, you will need to run the script with sudo: sudo activate-global-python-argcomplete, or run the script with --help to see other options.

Zsh Support

Argcomplete supports zsh. On top of plain completions like in bash, zsh allows you to see argparse help strings as completion descriptions. All shellcode included with argcomplete is compatible with both bash and zsh, so the same completer commands activate-global-python-argcomplete and eval "$(register-python-argcomplete my-python-app)" work for zsh as well.

Python Support

Argcomplete requires Python 3.7+.

Support for other shells

Argcomplete maintainers provide support only for the bash and zsh shells on Linux and MacOS. For resources related to other shells and platforms, including fish, tcsh, xonsh, powershell, and Windows, please see the contrib directory.

Common Problems

If global completion is not completing your script, bash may have registered a default completion function:

$ complete | grep my-python-app
complete -F _minimal my-python-app

You can fix this by restarting your shell, or by running complete -r my-python-app.


Set the _ARC_DEBUG variable in your shell to enable verbose debug output every time argcomplete runs. This will disrupt the command line composition state of your terminal, but make it possible to see the internal state of the completer if it encounters problems.


Inspired and informed by the optcomplete module by Martin Blais.



Please report bugs, issues, feature requests, etc. on GitHub.


Copyright 2012-2023, Andrey Kislyuk and argcomplete contributors. Licensed under the terms of the Apache License, Version 2.0. Distribution of the LICENSE and NOTICE files with source copies of this package and derivative works is REQUIRED as specified by the Apache License.
Popular Completion Projects
Popular Tabs Projects
Popular Text Processing Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Bash Completion