Skip to main content

Bash tab completion for argparse

Project description

Argcomplete provides easy and extensible automatic tab completion of arguments for your Python script.

It makes two assumptions:

  • You’re using bash 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

See Activating global completion below if the second step reports an error.


Python code (e.g.

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

Shellcode (only necessary if global completion is not activated - see Activating global completion below), to be put in e.g. .bashrc:

eval "$(register-python-argcomplete"


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.

Specifying completers

You can specify custom completion functions for your options and arguments. Completers are called with the following keyword arguments:

  • prefix: The prefix text of the last word before the cursor on the command line. All returned completions should begin with this prefix.

  • action: The argparse.Action instance that this completer was called for.

  • parser: The argparse.ArgumentParser instance that the action was taken by.

Completers should return their completions as a list of strings. An example completer for names of environment variables might look like this:

def EnvironCompleter(prefix, **kwargs):
    return (v for v in os.environ if v.startswith(prefix))

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, prefix, **kwargs):
        return (c for c in self.choices if c.startswith(prefix))

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'))

Activating global completion

In global completion mode, you don’t have to register each argcomplete-capable executable separately. Instead, bash 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.

The script activate-global-python-argcomplete will try to install the file etc/bash_completion.d/ (see on GitHub) into an appropriate location on your system (/etc/bash_completion.d/ or ~/.bash_completion.d/). If it fails, but you know the correct location of your bash completion scripts directory, you can specify it with --dest:

activate-global-python-argcomplete --dest=/path/to/bash_completion.d

Otherwise, you can redirect its shellcode output into a file:

activate-global-python-argcomplete --dest=- > file

The file’s contents should then be sourced in e.g. ~/.bashrc.


Inspired and informed by the optcomplete module by Martin Blais.

Project details

Release history Release notifications | RSS feed

Download files

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

Source Distribution

argcomplete-0.2.8.tar.gz (12.7 kB view hashes)

Uploaded Source

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