The argparse module includes tools for building command line argument and option processors. It was added to Python 2.7 as a replacement for optparse . The implementation of argparse supports features that would not have been easy to add to optparse , and that would have required backwards-incompatible API changes, so a new module was brought into the library instead. optparse is now deprecated.

The first step when using argparse is to create a parser object and tell it what arguments to expect. The parser can then be used to process the command-line arguments when the program runs. The constructor for the parser class ( ArgumentParser ) takes several arguments to set up the description used in the help text for the program and other global behaviors or settings.

The default action is to store the argument value. If a type is provided, the value is converted to that type before it is stored. If the dest argument is provided, the value is saved using that name when the command-line arguments are parsed.

argparse is a complete argument processing library. Arguments can trigger different actions, specified by the action argument to add_argument() . Supported actions include storing the argument (singly, or as part of a list), storing a constant value when the argument is encountered (including special handling for true/false values for Boolean switches), counting the number of times an argument is seen, and calling a callback to use custom processing instructions.

The return value from parse_args() is a Namespace containing the arguments to the command. The object holds the argument values as attributes, so if the argument’s dest is set to "myoption" , the value is accessible as args.myoption .

After all of the arguments are defined, parse the command-line by passing a sequence of argument strings to parse_args() . By default, the arguments are taken from sys.argv[1:] , but any list of strings can be used. The options are processed using the GNU/POSIX syntax, so option and argument values can be mixed in the sequence.

Simple Examples¶

Here is a simple example with three different options: a Boolean option ( -a ), a simple string option ( -b ), and an integer option ( -c ).

argparse_short.py ¶ import argparse parser = argparse . ArgumentParser ( description = 'Short sample app' ) parser . add_argument ( '-a' , action = "store_true" , default = False ) parser . add_argument ( '-b' , action = "store" , dest = "b" ) parser . add_argument ( '-c' , action = "store" , dest = "c" , type = int ) print ( parser . parse_args ([ '-a' , '-bval' , '-c' , '3' ]))

There are a few ways to pass values to single character options. The previous example uses two different forms, -bval and -c val .

$ python3 argparse_short.py Namespace(a=True, b='val', c=3)

The type of the value associated with 'c' in the output is an integer, since the ArgumentParser was told to convert the argument before storing it.

“Long” option names, with more than a single character in their name, are handled in the same way.

argparse_long.py ¶ import argparse parser = argparse . ArgumentParser ( description = 'Example with long option names' , ) parser . add_argument ( '--noarg' , action = "store_true" , default = False ) parser . add_argument ( '--witharg' , action = "store" , dest = "witharg" ) parser . add_argument ( '--witharg2' , action = "store" , dest = "witharg2" , type = int ) print ( parser . parse_args ( [ '--noarg' , '--witharg' , 'val' , '--witharg2=3' ] ) )

The results are similar.

$ python3 argparse_long.py Namespace(noarg=True, witharg='val', witharg2=3)

argparse is a full command-line argument parser tool, and handles both optional and required arguments.

argparse_arguments.py ¶ import argparse parser = argparse . ArgumentParser ( description = 'Example with nonoptional arguments' , ) parser . add_argument ( 'count' , action = "store" , type = int ) parser . add_argument ( 'units' , action = "store" ) print ( parser . parse_args ())

In this example, the “count” argument is an integer and the “units” argument is saved as a string. If either is left off of the command-line, or the value given cannot be converted to the right type, an error is reported.

$ python3 argparse_arguments.py 3 inches Namespace(count=3, units='inches') $ python3 argparse_arguments.py some inches usage: argparse_arguments.py [-h] count units argparse_arguments.py: error: argument count: invalid int value: 'some' $ python3 argparse_arguments.py usage: argparse_arguments.py [-h] count units argparse_arguments.py: error: the following arguments are required: count, units

Argument Actions¶ Any of six built-in actions can be triggered when an argument is encountered. store Save the value, after optionally converting it to a different type. This is the default action taken if none is specified explicitly. store_const Save a value defined as part of the argument specification, rather than a value that comes from the arguments being parsed. This is typically used to implement command-line flags that are not Booleans. store_true / store_false Save the appropriate Boolean value. These actions are used to implement Boolean switches. append Save the value to a list. Multiple values are saved if the argument is repeated. append_const Save a value defined in the argument specification to a list. version Prints version details about the program and then exits. This example program demonstrates each action type, with the minimum configuration needed for each to work. argparse_action.py ¶ import argparse parser = argparse . ArgumentParser () parser . add_argument ( '-s' , action = 'store' , dest = 'simple_value' , help = 'Store a simple value' ) parser . add_argument ( '-c' , action = 'store_const' , dest = 'constant_value' , const = 'value-to-store' , help = 'Store a constant value' ) parser . add_argument ( '-t' , action = 'store_true' , default = False , dest = 'boolean_t' , help = 'Set a switch to true' ) parser . add_argument ( '-f' , action = 'store_false' , default = True , dest = 'boolean_f' , help = 'Set a switch to false' ) parser . add_argument ( '-a' , action = 'append' , dest = 'collection' , default = [], help = 'Add repeated values to a list' ) parser . add_argument ( '-A' , action = 'append_const' , dest = 'const_collection' , const = 'value-1-to-append' , default = [], help = 'Add different values to list' ) parser . add_argument ( '-B' , action = 'append_const' , dest = 'const_collection' , const = 'value-2-to-append' , help = 'Add different values to list' ) parser . add_argument ( '--version' , action = 'version' , version = ' %(prog)s 1.0' ) results = parser . parse_args () print ( 'simple_value = {!r} ' . format ( results . simple_value )) print ( 'constant_value = {!r} ' . format ( results . constant_value )) print ( 'boolean_t = {!r} ' . format ( results . boolean_t )) print ( 'boolean_f = {!r} ' . format ( results . boolean_f )) print ( 'collection = {!r} ' . format ( results . collection )) print ( 'const_collection = {!r} ' . format ( results . const_collection )) The -t and -f options are configured to modify different option values, each storing either True or False. The dest values for -A and -B are the same so that their constant values are appended to the same list. $ python3 argparse_action.py -h usage: argparse_action.py [-h] [-s SIMPLE_VALUE] [-c] [-t] [-f] [-a COLLECTION] [-A] [-B] [--version] optional arguments: -h, --help show this help message and exit -s SIMPLE_VALUE Store a simple value -c Store a constant value -t Set a switch to true -f Set a switch to false -a COLLECTION Add repeated values to a list -A Add different values to list -B Add different values to list --version show program's version number and exit $ python3 argparse_action.py -s value simple_value = 'value' constant_value = None boolean_t = False boolean_f = True collection = [] const_collection = [] $ python3 argparse_action.py -c simple_value = None constant_value = 'value-to-store' boolean_t = False boolean_f = True collection = [] const_collection = [] $ python3 argparse_action.py -t simple_value = None constant_value = None boolean_t = True boolean_f = True collection = [] const_collection = [] $ python3 argparse_action.py -f simple_value = None constant_value = None boolean_t = False boolean_f = False collection = [] const_collection = [] $ python3 argparse_action.py -a one -a two -a three simple_value = None constant_value = None boolean_t = False boolean_f = True collection = ['one', 'two', 'three'] const_collection = [] $ python3 argparse_action.py -B -A simple_value = None constant_value = None boolean_t = False boolean_f = True collection = [] const_collection = ['value-2-to-append', 'value-1-to-append'] $ python3 argparse_action.py --version argparse_action.py 1.0

Option Prefixes¶ The default syntax for options is based on the Unix convention of signifying command-line switches using a dash prefix (“ - “). argparse supports other prefixes, so a program can conform to the local platform default (i.e., use “ / ” on Windows) or follow a different convention. argparse_prefix_chars.py ¶ import argparse parser = argparse . ArgumentParser ( description = 'Change the option prefix characters' , prefix_chars = '-+/' , ) parser . add_argument ( '-a' , action = "store_false" , default = None , help = 'Turn A off' , ) parser . add_argument ( '+a' , action = "store_true" , default = None , help = 'Turn A on' , ) parser . add_argument ( '//noarg' , '++noarg' , action = "store_true" , default = False ) print ( parser . parse_args ()) Set the prefix_chars parameter for the ArgumentParser to a string containing all of the characters that should be allowed to signify options. It is important to understand that although prefix_chars establishes the allowed switch characters, the individual argument definitions specify the syntax for a given switch. This gives explicit control over whether options using different prefixes are aliases (such as might be the case for platform-independent command-line syntax) or alternatives (e.g., using “ + ” to indicate turning a switch on and “ - ” to turn it off). In the previous example, +a and -a are separate arguments, and //noarg can also be given as ++noarg , but not --noarg . $ python3 argparse_prefix_chars.py -h usage: argparse_prefix_chars.py [-h] [-a] [+a] [//noarg] Change the option prefix characters optional arguments: -h, --help show this help message and exit -a Turn A off +a Turn A on //noarg, ++noarg $ python3 argparse_prefix_chars.py +a Namespace(a=True, noarg=False) $ python3 argparse_prefix_chars.py -a Namespace(a=False, noarg=False) $ python3 argparse_prefix_chars.py //noarg Namespace(a=None, noarg=True) $ python3 argparse_prefix_chars.py ++noarg Namespace(a=None, noarg=True) $ python3 argparse_prefix_chars.py --noarg usage: argparse_prefix_chars.py [-h] [-a] [+a] [//noarg] argparse_prefix_chars.py: error: unrecognized arguments: --noarg