argparse — Parser for command-line options, arguments and sub-commands

New in version 3.2.

Source code: Lib/argparse.py

Tutorial

This page contains the API reference information. For a more gentle introduction to Python
command-line parsing, have a look at the argparse tutorial.

The argparse module makes it easy to write user-friendly command-line interfaces. The program
defines what arguments it requires, and argparse will figure out how to parse those out of sys.argv.
The argparse module also automatically generates help and usage messages and issues errors when
users give the program invalid arguments.

Example

The following code is a Python program that takes a list of integers and produces either the sum or
the max:

import argparse

parser = argparse.ArgumentParser(description='Process some integers.')

parser.add_argument('integers', metavar='N', type=int, nargs='+',

help='an integer for the accumulator')

parser.add_argument('--sum', dest='accumulate', action='store_const',

const=sum, default=max,

help='sum the integers (default: find the max)')

args = parser.parse_args()

print(args.accumulate(args.integers))

Assuming the Python code above is saved into a file called prog.py, it can be run at the command line
and provides useful help messages:
$ python prog.py -h

usage: prog.py [-h] [--sum] N [N ...]

Process some integers.

positional arguments:

N an integer for the accumulator

options:

-h, --help show this help message and exit

--sum sum the integers (default: find the max)

When run with the appropriate arguments, it prints either the sum or the max of the command-line
integers:

$ python prog.py 1 2 3 4

$ python prog.py 1 2 3 4 --sum

10

If invalid arguments are passed in, it will issue an error:

$ python prog.py a b c

usage: prog.py [-h] [--sum] N [N ...]

prog.py: error: argument N: invalid int value: 'a'

The following sections walk you through this example.

Creating a parser

The first step in using the argparse is creating an ArgumentParser object:

>>>

>>> parser = argparse.ArgumentParser(description='Process some integers.')

The ArgumentParser object will hold all the information necessary to parse the command line into
Python data types.

Adding arguments

Filling an ArgumentParser with information about program arguments is done by making calls to the
add_argument() method. Generally, these calls tell the ArgumentParser how to take the strings on
the command line and turn them into objects. This information is stored and used when parse_args()
is called. For example:

>>>

>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',

... help='an integer for the accumulator')

>>> parser.add_argument('--sum', dest='accumulate', action='store_const',

... const=sum, default=max,

... help='sum the integers (default: find the max)')

Later, calling parse_args() will return an object with two attributes, integers and accumulate. The
integers attribute will be a list of one or more ints, and the accumulate attribute will be either the
sum() function, if --sum was specified at the command line, or the max() function if it was not.

Parsing arguments

ArgumentParser parses arguments through the parse_args() method. This will inspect the command
line, convert each argument to the appropriate type and then invoke the appropriate action. In most
cases, this means a simple Namespace object will be built up from attributes parsed out of the
command line:

>>>

>>> parser.parse_args(['--sum', '7', '-1', '42'])

Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

In a script, parse_args() will typically be called with no arguments, and the ArgumentParser will
automatically determine the command-line arguments from sys.argv.

ArgumentParser objects

class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None,

parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None,
argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True,
exit_on_error=True)
Create a new ArgumentParser object. All parameters should be passed as keyword arguments. Each
parameter has its own more detailed description below, but in short they are:

prog - The name of the program (default: os.path.basename(sys.argv[0]))

usage - The string describing the program usage (default: generated from arguments added to
parser)

description - Text to display before the argument help (default: none)

epilog - Text to display after the argument help (default: none)

parents - A list of ArgumentParser objects whose arguments should also be included

formatter_class - A class for customizing the help output

prefix_chars - The set of characters that prefix optional arguments (default: ‘-‘)

fromfile_prefix_chars - The set of characters that prefix files from which additional arguments should
be read (default: None)

argument_default - The global default value for arguments (default: None)

conflict_handler - The strategy for resolving conflicting optionals (usually unnecessary)

add_help - Add a -h/--help option to the parser (default: True)

allow_abbrev - Allows long options to be abbreviated if the abbreviation is unambiguous. (default:

True)

exit_on_error - Determines whether or not ArgumentParser exits with error info when an error
occurs. (default: True)
Changed in version 3.5: allow_abbrev parameter was added.

Changed in version 3.8: In previous versions, allow_abbrev also disabled grouping of short flags such
as -vv to mean -v -v.

Changed in version 3.9: exit_on_error parameter was added.

The following sections describe how each of these are used.

prog

By default, ArgumentParser objects use sys.argv[0] to determine how to display the name of the
program in help messages. This default is almost always desirable because it will make the help
messages match how the program was invoked on the command line. For example, consider a file
named myprogram.py with the following code:

import argparse

parser = argparse.ArgumentParser()

parser.add_argument('--foo', help='foo help')

args = parser.parse_args()

The help for this program will display myprogram.py as the program name (regardless of where the
program was invoked from):

$ python myprogram.py --help

usage: myprogram.py [-h] [--foo FOO]

options:

-h, --help show this help message and exit

--foo FOO foo help

$ cd ..

$ python subdir/myprogram.py --help

usage: myprogram.py [-h] [--foo FOO]

options:
-h, --help show this help message and exit

--foo FOO foo help

To change this default behavior, another value can be supplied using the prog= argument to
ArgumentParser:

>>>

>>> parser = argparse.ArgumentParser(prog='myprogram')

>>> parser.print_help()

usage: myprogram [-h]

options:

-h, --help show this help message and exit

Note that the program name, whether determined from sys.argv[0] or from the prog= argument, is
available to help messages using the %(prog)s format specifier.

>>>

>>> parser = argparse.ArgumentParser(prog='myprogram')

>>> parser.add_argument('--foo', help='foo of the %(prog)s program')

>>> parser.print_help()

usage: myprogram [-h] [--foo FOO]

options:

-h, --help show this help message and exit

--foo FOO foo of the myprogram program

usage

By default, ArgumentParser calculates the usage message from the arguments it contains:

>>>

>>> parser = argparse.ArgumentParser(prog='PROG')

>>> parser.add_argument('--foo', nargs='?', help='foo help')

>>> parser.add_argument('bar', nargs='+', help='bar help')

>>> parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]

positional arguments:

bar bar help

options:

-h, --help show this help message and exit

--foo [FOO] foo help

The default message can be overridden with the usage= keyword argument:

>>>

>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')

>>> parser.add_argument('--foo', nargs='?', help='foo help')

>>> parser.add_argument('bar', nargs='+', help='bar help')

>>> parser.print_help()

usage: PROG [options]

positional arguments:

bar bar help

options:

-h, --help show this help message and exit

--foo [FOO] foo help

The %(prog)s format specifier is available to fill in the program name in your usage messages.

description

Most calls to the ArgumentParser constructor will use the description= keyword argument. This
argument gives a brief description of what the program does and how it works. In help messages, the
description is displayed between the command-line usage string and the help messages for the
various arguments:

>>>
>>> parser = argparse.ArgumentParser(description='A foo that bars')

>>> parser.print_help()

usage: argparse.py [-h]

A foo that bars

options:

-h, --help show this help message and exit

By default, the description will be line-wrapped so that it fits within the given space. To change this
behavior, see the formatter_class argument.

epilog

Some programs like to display additional description of the program after the description of the
arguments. Such text can be specified using the epilog= argument to ArgumentParser:

>>>

>>> parser = argparse.ArgumentParser(

... description='A foo that bars',

... epilog="And that's how you'd foo a bar")

>>> parser.print_help()

usage: argparse.py [-h]

A foo that bars

options:

-h, --help show this help message and exit

And that's how you'd foo a bar

As with the description argument, the epilog= text is by default line-wrapped, but this behavior can
be adjusted with the formatter_class argument to ArgumentParser.

parents
Sometimes, several parsers share a common set of arguments. Rather than repeating the definitions
of these arguments, a single parser with all the shared arguments and passed to parents= argument
to ArgumentParser can be used. The parents= argument takes a list of ArgumentParser objects,
collects all the positional and optional actions from them, and adds these actions to the
ArgumentParser object being constructed:

>>>

>>> parent_parser = argparse.ArgumentParser(add_help=False)

>>> parent_parser.add_argument('--parent', type=int)

>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])

>>> foo_parser.add_argument('foo')

>>> foo_parser.parse_args(['--parent', '2', 'XXX'])

Namespace(foo='XXX', parent=2)

>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])

>>> bar_parser.add_argument('--bar')

>>> bar_parser.parse_args(['--bar', 'YYY'])

Namespace(bar='YYY', parent=None)

Note that most parent parsers will specify add_help=False. Otherwise, the ArgumentParser will see
two -h/--help options (one in the parent and one in the child) and raise an error.

Note You must fully initialize the parsers before passing them via parents=. If you change the parent
parsers after the child parser, those changes will not be reflected in the child.

formatter_class

ArgumentParser objects allow the help formatting to be customized by specifying an alternate

formatting class. Currently, there are four such classes:

class argparse.RawDescriptionHelpFormatter

class argparse.RawTextHelpFormatter

class argparse.ArgumentDefaultsHelpFormatter

class argparse.MetavarTypeHelpFormatter
RawDescriptionHelpFormatter and RawTextHelpFormatter give more control over how textual
descriptions are displayed. By default, ArgumentParser objects line-wrap the description and epilog
texts in command-line help messages:

>>>

>>> parser = argparse.ArgumentParser(

... prog='PROG',

... description='''this description

... was indented weird

... but that is okay''',

... epilog='''

... likewise for this epilog whose whitespace will

... be cleaned up and whose words will be wrapped

... across a couple lines''')

>>> parser.print_help()

usage: PROG [-h]

this description was indented weird but that is okay

options:

-h, --help show this help message and exit

likewise for this epilog whose whitespace will be cleaned up and whose words

will be wrapped across a couple lines

Passing RawDescriptionHelpFormatter as formatter_class= indicates that description and epilog are

already correctly formatted and should not be line-wrapped:

>>>

>>> parser = argparse.ArgumentParser(

... prog='PROG',

... formatter_class=argparse.RawDescriptionHelpFormatter,

... description=textwrap.dedent('''\
... Please do not mess up this text!

... --------------------------------

... I have indented it

... exactly the way

... I want it

... '''))

>>> parser.print_help()

usage: PROG [-h]

Please do not mess up this text!

--------------------------------

I have indented it

exactly the way

I want it

options:

-h, --help show this help message and exit

RawTextHelpFormatter maintains whitespace for all sorts of help text, including argument
descriptions. However, multiple new lines are replaced with one. If you wish to preserve multiple
blank lines, add spaces between the newlines.

ArgumentDefaultsHelpFormatter automatically adds information about default values to each of the

argument help messages:

>>>

>>> parser = argparse.ArgumentParser(

... prog='PROG',

... formatter_class=argparse.ArgumentDefaultsHelpFormatter)

>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')

>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')

>>> parser.print_help()

usage: PROG [-h] [--foo FOO] [bar ...]

positional arguments:

bar BAR! (default: [1, 2, 3])

options:

-h, --help show this help message and exit

--foo FOO FOO! (default: 42)

MetavarTypeHelpFormatter uses the name of the type argument for each argument as the display
name for its values (rather than using the dest as the regular formatter does):

>>>

>>> parser = argparse.ArgumentParser(

... prog='PROG',

... formatter_class=argparse.MetavarTypeHelpFormatter)

>>> parser.add_argument('--foo', type=int)

>>> parser.add_argument('bar', type=float)

>>> parser.print_help()

usage: PROG [-h] [--foo int] float

positional arguments:

float

options:

-h, --help show this help message and exit

--foo int

prefix_chars

Most command-line options will use - as the prefix, e.g. -f/--foo. Parsers that need to support
different or additional prefix characters, e.g. for options like +f or /foo, may specify them using the
prefix_chars= argument to the ArgumentParser constructor:

>>>

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')

>>> parser.add_argument('+f')

>>> parser.add_argument('++bar')

>>> parser.parse_args('+f X ++bar Y'.split())

Namespace(bar='Y', f='X')

The prefix_chars= argument defaults to '-'. Supplying a set of characters that does not include - will
cause -f/--foo options to be disallowed.

fromfile_prefix_chars

Sometimes, for example when dealing with a particularly long argument lists, it may make sense to
keep the list of arguments in a file rather than typing it out at the command line. If the
fromfile_prefix_chars= argument is given to the ArgumentParser constructor, then arguments that
start with any of the specified characters will be treated as files, and will be replaced by the
arguments they contain. For example:

>>>

>>> with open('args.txt', 'w') as fp:

... fp.write('-f\nbar')

>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')

>>> parser.add_argument('-f')

>>> parser.parse_args(['-f', 'foo', '@args.txt'])

Namespace(f='bar')

Arguments read from a file must by default be one per line (but see also convert_arg_line_to_args())
and are treated as if they were in the same place as the original file referencing argument on the
command line. So in the example above, the expression ['-f', 'foo', '@args.txt'] is considered
equivalent to the expression ['-f', 'foo', '-f', 'bar'].

The fromfile_prefix_chars= argument defaults to None, meaning that arguments will never be
treated as file references.

argument_default

Generally, argument defaults are specified either by passing a default to add_argument() or by calling
the set_defaults() methods with a specific set of name-value pairs. Sometimes however, it may be
useful to specify a single parser-wide default for arguments. This can be accomplished by passing the
argument_default= keyword argument to ArgumentParser. For example, to globally suppress
attribute creation on parse_args() calls, we supply argument_default=SUPPRESS:
>>>

>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)

>>> parser.add_argument('--foo')

>>> parser.add_argument('bar', nargs='?')

>>> parser.parse_args(['--foo', '1', 'BAR'])

Namespace(bar='BAR', foo='1')

>>> parser.parse_args([])

Namespace()

allow_abbrev

Normally, when you pass an argument list to the parse_args() method of an ArgumentParser, it
recognizes abbreviations of long options.

This feature can be disabled by setting allow_abbrev to False:

>>>

>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)

>>> parser.add_argument('--foobar', action='store_true')

>>> parser.add_argument('--foonley', action='store_false')

>>> parser.parse_args(['--foon'])

usage: PROG [-h] [--foobar] [--foonley]

PROG: error: unrecognized arguments: --foon

New in version 3.5.

conflict_handler

ArgumentParser objects do not allow two actions with the same option string. By default,
ArgumentParser objects raise an exception if an attempt is made to create an argument with an
option string that is already in use:

>>>

>>> parser = argparse.ArgumentParser(prog='PROG')

>>> parser.add_argument('-f', '--foo', help='old foo help')

>>> parser.add_argument('--foo', help='new foo help')

Traceback (most recent call last):

..

ArgumentError: argument --foo: conflicting option string(s): --foo

Sometimes (e.g. when using parents) it may be useful to simply override any older arguments with
the same option string. To get this behavior, the value 'resolve' can be supplied to the
conflict_handler= argument of ArgumentParser:

>>>

>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')

>>> parser.add_argument('-f', '--foo', help='old foo help')

>>> parser.add_argument('--foo', help='new foo help')

>>> parser.print_help()

usage: PROG [-h] [-f FOO] [--foo FOO]

options:

-h, --help show this help message and exit

-f FOO old foo help

--foo FOO new foo help

Note that ArgumentParser objects only remove an action if all of its option strings are overridden. So,
in the example above, the old -f/--foo action is retained as the -f action, because only the --foo option
string was overridden.

add_help

By default, ArgumentParser objects add an option which simply displays the parser’s help message.
For example, consider a file named myprogram.py containing the following code:

import argparse

parser = argparse.ArgumentParser()

parser.add_argument('--foo', help='foo help')

args = parser.parse_args()

If -h or --help is supplied at the command line, the ArgumentParser help will be printed:

$ python myprogram.py --help

usage: myprogram.py [-h] [--foo FOO]

options:

-h, --help show this help message and exit

--foo FOO foo help

Occasionally, it may be useful to disable the addition of this help option. This can be achieved by
passing False as the add_help= argument to ArgumentParser:

>>>

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)

>>> parser.add_argument('--foo', help='foo help')

>>> parser.print_help()

usage: PROG [--foo FOO]

options:

--foo FOO foo help

The help option is typically -h/--help. The exception to this is if the prefix_chars= is specified and does
not include -, in which case -h and --help are not valid options. In this case, the first character in
prefix_chars is used to prefix the help options:

>>>

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')

>>> parser.print_help()

usage: PROG [+h]

options:

+h, ++help show this help message and exit

exit_on_error

Normally, when you pass an invalid argument list to the parse_args() method of an ArgumentParser,
it will exit with error info.

If the user would like to catch errors manually, the feature can be enabled by setting exit_on_error to
False:
>>>

>>> parser = argparse.ArgumentParser(exit_on_error=False)

>>> parser.add_argument('--integers', type=int)

_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None,

type=<class 'int'>, choices=None, help=None, metavar=None)

>>> try:

... parser.parse_args('--integers a'.split())

... except argparse.ArgumentError:

... print('Catching an argumentError')

...

Catching an argumentError

New in version 3.9.

The add_argument() method

ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][,

required][, help][, metavar][, dest])

Define how a single command-line argument should be parsed. Each parameter has its own more
detailed description below, but in short they are:

name or flags - Either a name or a list of option strings, e.g. foo or -f, --foo.

action - The basic type of action to be taken when this argument is encountered at the command
line.

nargs - The number of command-line arguments that should be consumed.

const - A constant value required by some action and nargs selections.

default - The value produced if the argument is absent from the command line and if it is absent from
the namespace object.

type - The type to which the command-line argument should be converted.

choices - A container of the allowable values for the argument.

required - Whether or not the command-line option may be omitted (optionals only).

help - A brief description of what the argument does.

metavar - A name for the argument in usage messages.

dest - The name of the attribute to be added to the object returned by parse_args().

The following sections describe how each of these are used.

name or flags

The add_argument() method must know whether an optional argument, like -f or --foo, or a
positional argument, like a list of filenames, is expected. The first arguments passed to
add_argument() must therefore be either a series of flags, or a simple argument name.

For example, an optional argument could be created like:

>>>

>>> parser.add_argument('-f', '--foo')

while a positional argument could be created like:

>>>

>>> parser.add_argument('bar')

When parse_args() is called, optional arguments will be identified by the - prefix, and the remaining
arguments will be assumed to be positional:

>>>

>>> parser = argparse.ArgumentParser(prog='PROG')

>>> parser.add_argument('-f', '--foo')

>>> parser.add_argument('bar')

>>> parser.parse_args(['BAR'])

Namespace(bar='BAR', foo=None)

>>> parser.parse_args(['BAR', '--foo', 'FOO'])

Namespace(bar='BAR', foo='FOO')

>>> parser.parse_args(['--foo', 'FOO'])

usage: PROG [-h] [-f FOO] bar

PROG: error: the following arguments are required: bar

action

ArgumentParser objects associate command-line arguments with actions. These actions can do just
about anything with the command-line arguments associated with them, though most actions simply
add an attribute to the object returned by parse_args(). The action keyword argument specifies how
the command-line arguments should be handled. The supplied actions are:

'store' - This just stores the argument’s value. This is the default action. For example:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo')

>>> parser.parse_args('--foo 1'.split())

Namespace(foo='1')

'store_const' - This stores the value specified by the const keyword argument; note that the const
keyword argument defaults to None. The 'store_const' action is most commonly used with optional
arguments that specify some sort of flag. For example:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo', action='store_const', const=42)

>>> parser.parse_args(['--foo'])

Namespace(foo=42)

'store_true' and 'store_false' - These are special cases of 'store_const' used for storing the values
True and False respectively. In addition, they create default values of False and True respectively. For
example:
>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo', action='store_true')

>>> parser.add_argument('--bar', action='store_false')

>>> parser.add_argument('--baz', action='store_false')

>>> parser.parse_args('--foo --bar'.split())

Namespace(foo=True, bar=False, baz=True)

'append' - This stores a list, and appends each argument value to the list. This is useful to allow an
option to be specified multiple times. Example usage:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo', action='append')

>>> parser.parse_args('--foo 1 --foo 2'.split())

Namespace(foo=['1', '2'])

'append_const' - This stores a list, and appends the value specified by the const keyword argument
to the list; note that the const keyword argument defaults to None. The 'append_const' action is
typically useful when multiple arguments need to store constants to the same list. For example:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--str', dest='types', action='append_const', const=str)

>>> parser.add_argument('--int', dest='types', action='append_const', const=int)

>>> parser.parse_args('--str --int'.split())

Namespace(types=[<class 'str'>, <class 'int'>])

'count' - This counts the number of times a keyword argument occurs. For example, this is useful for
increasing verbosity levels:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--verbose', '-v', action='count', default=0)

>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)

Note, the default will be None unless explicitly set to 0.

'help' - This prints a complete help message for all the options in the current parser and then exits. By
default a help action is automatically added to the parser. See ArgumentParser for details of how the
output is created.

'version' - This expects a version= keyword argument in the add_argument() call, and prints version
information and exits when invoked:

>>>

>>> import argparse

>>> parser = argparse.ArgumentParser(prog='PROG')

>>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')

>>> parser.parse_args(['--version'])

PROG 2.0

'extend' - This stores a list, and extends each argument value to the list. Example usage:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument("--foo", action="extend", nargs="+", type=str)

>>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])

Namespace(foo=['f1', 'f2', 'f3', 'f4'])

New in version 3.8.

You may also specify an arbitrary action by passing an Action subclass or other object that
implements the same interface. The BooleanOptionalAction is available in argparse and adds support
for boolean actions such as --foo and --no-foo:

>>>

>>> import argparse

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)

>>> parser.parse_args(['--no-foo'])

Namespace(foo=False)

New in version 3.9.

The recommended way to create a custom action is to extend Action, overriding the __call__ method
and optionally the __init__ and format_usage methods.

An example of a custom action:

>>>

>>> class FooAction(argparse.Action):

... def __init__(self, option_strings, dest, nargs=None, **kwargs):

... if nargs is not None:

... raise ValueError("nargs not allowed")

... super().__init__(option_strings, dest, **kwargs)

... def __call__(self, parser, namespace, values, option_string=None):

... print('%r %r %r' % (namespace, values, option_string))

... setattr(namespace, self.dest, values)

...

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo', action=FooAction)

>>> parser.add_argument('bar', action=FooAction)

>>> args = parser.parse_args('1 --foo 2'.split())

Namespace(bar=None, foo=None) '1' None

Namespace(bar='1', foo=None) '2' '--foo'

>>> args

Namespace(bar='1', foo='2')

For more details, see Action.

nargs
ArgumentParser objects usually associate a single command-line argument with a single action to be
taken. The nargs keyword argument associates a different number of command-line arguments with
a single action. The supported values are:

N (an integer). N arguments from the command line will be gathered together into a list. For
example:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo', nargs=2)

>>> parser.add_argument('bar', nargs=1)

>>> parser.parse_args('c --foo a b'.split())

Namespace(bar=['c'], foo=['a', 'b'])

Note that nargs=1 produces a list of one item. This is different from the default, in which the item is
produced by itself.

'?'. One argument will be consumed from the command line if possible, and produced as a single
item. If no command-line argument is present, the value from default will be produced. Note that for
optional arguments, there is an additional case - the option string is present but not followed by a
command-line argument. In this case the value from const will be produced. Some examples to
illustrate this:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo', nargs='?', const='c', default='d')

>>> parser.add_argument('bar', nargs='?', default='d')

>>> parser.parse_args(['XX', '--foo', 'YY'])

Namespace(bar='XX', foo='YY')

>>> parser.parse_args(['XX', '--foo'])

Namespace(bar='XX', foo='c')

>>> parser.parse_args([])

Namespace(bar='d', foo='d')

One of the more common uses of nargs='?' is to allow optional input and output files:
>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),

... default=sys.stdin)

>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),

... default=sys.stdout)

>>> parser.parse_args(['input.txt', 'output.txt'])

Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,

outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)

>>> parser.parse_args([])

Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,

outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)

'*'. All command-line arguments present are gathered into a list. Note that it generally doesn’t make
much sense to have more than one positional argument with nargs='*', but multiple optional
arguments with nargs='*' is possible. For example:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo', nargs='*')

>>> parser.add_argument('--bar', nargs='*')

>>> parser.add_argument('baz', nargs='*')

>>> parser.parse_args('a b --foo x y --bar 1 2'.split())

Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

'+'. Just like '*', all command-line args present are gathered into a list. Additionally, an error message
will be generated if there wasn’t at least one command-line argument present. For example:

>>>

>>> parser = argparse.ArgumentParser(prog='PROG')

>>> parser.add_argument('foo', nargs='+')

>>> parser.parse_args(['a', 'b'])

Namespace(foo=['a', 'b'])

>>> parser.parse_args([])
usage: PROG [-h] foo [foo ...]

PROG: error: the following arguments are required: foo

If the nargs keyword argument is not provided, the number of arguments consumed is determined
by the action. Generally this means a single command-line argument will be consumed and a single
item (not a list) will be produced.

const

The const argument of add_argument() is used to hold constant values that are not read from the
command line but are required for the various ArgumentParser actions. The two most common uses
of it are:

When add_argument() is called with action='store_const' or action='append_const'. These actions

add the const value to one of the attributes of the object returned by parse_args(). See the action
description for examples. If const is not provided to add_argument(), it will receive a default value of
None.

When add_argument() is called with option strings (like -f or --foo) and nargs='?'. This creates an
optional argument that can be followed by zero or one command-line arguments. When parsing the
command line, if the option string is encountered with no command-line argument following it, the
value of const will be assumed to be None instead. See the nargs description for examples.

Changed in version 3.11: const=None by default, including when action='append_const' or

action='store_const'.

default

All optional arguments and some positional arguments may be omitted at the command line. The
default keyword argument of add_argument(), whose value defaults to None, specifies what value
should be used if the command-line argument is not present. For optional arguments, the default
value is used when the option string was not present at the command line:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo', default=42)

>>> parser.parse_args(['--foo', '2'])

Namespace(foo='2')

>>> parser.parse_args([])
Namespace(foo=42)

If the target namespace already has an attribute set, the action default will not over write it:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo', default=42)

>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))

Namespace(foo=101)

If the default value is a string, the parser parses the value as if it were a command-line argument. In
particular, the parser applies any type conversion argument, if provided, before setting the attribute
on the Namespace return value. Otherwise, the parser uses the value as is:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--length', default='10', type=int)

>>> parser.add_argument('--width', default=10.5, type=int)

>>> parser.parse_args()

Namespace(length=10, width=10.5)

For positional arguments with nargs equal to ? or *, the default value is used when no command-line
argument was present:

>>>

>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('foo', nargs='?', default=42)

>>> parser.parse_args(['a'])

Namespace(foo='a')

>>> parser.parse_args([])

Namespace(foo=42)

Providing default=argparse.SUPPRESS causes no attribute to be added if the command-line argument

was not present:

>>>
>>> parser = argparse.ArgumentParser()

>>> parser.add_argument('--foo', default=argparse.SUPPRESS)

>>> parser.parse_args([])

Namespace()

>>> parser.parse_args(['--foo', '1'])

Namespace(foo='1')

type

By default, the parser reads command-line arguments in as simple strings. However, quite often the
command-line string should instead be interpreted as another type, such as a float or int. The type
keyword for add_argument() allows any necessary type-checking and type conversions to be
performed.

If the type keyword is used with the default keyword, the type converter is only applied if the default
is a string.

The argument to type can be any callable that accepts a single string. If the function raises
ArgumentTypeError, TypeError, or ValueError, the exception is caught and a nicely formatted error
message is displayed. No other exception types are handled.

Common built-in types and functions can be used as type converters:

import argparse

import pathlib

parser = argparse.ArgumentParser()

parser.add_argument('count', type=int)

parser.add_argument('distance', type=float)

parser.add_argument('street', type=ascii)

parser.add_argument('code_point', type=ord)

parser.add_argument('source_file', type=open)

parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))

parser.add_argument('datapath', type=pathlib.Path)

User defined functions can be used as well:

>>>

>>> def hyphenated(string):

... return '-'.join([word[:4] for word in string.casefold().split()])

...

>>> parser = argparse.ArgumentParser()

>>> _ = parser.add_argument('short_title', type=hyphenated)

>>> parser.parse_args(['"The Tale of Two Cities"'])

Namespace(short_title='"the-tale-of-two-citi')

The bool() function is not recommended as a type converter. All it does is convert empty strings to
False and non-empty strings to True. This is usually not what is desired.

In general, the type keyword is a convenience that should only be used for simple conversions that
can only raise one of the three supported exceptions. Anything with more interesting error-handling
or resource management should be done downstream after the arguments are parsed.

For example, JSON or YAML conversions have complex error cases that require better reporting than
can be given by the type keyword. A JSONDecodeError would not be well formatted and a
FileNotFound exception would not be handled at all.

Even FileType has its limitations for use with the type keyword. If one argument uses FileType and
then a subsequent argument fails, an error is reported but the file is not automatically closed. In this
case, it would be better to wait until after the parser has run and then use the with-statement to
manage the files.

For type checkers that simply check against a fixed set of values, consider using the choices keyword
instead.

choices

Some command-line arguments should be selected from a restricted set of values. These can be
handled by passing a container object as the choices keyword argument to add_argument(). When
the command line is parsed, argument values will be checked, and an error message will be displayed
if the argument was not one of the acceptable values:

>>>
>>> parser = argparse.ArgumentParser(prog='game.py')

>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])

>>> parser.parse_args(['rock'])

Namespace(move='rock')

>>> parser.parse_args(['fire'])

usage: game.py [-h] {rock,paper,scissors}

game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',

'paper', 'scissors')

Note that inclusion in the choices container is checked after any type conversions have been
performed, so the type of the objects in the choices container should match the type specified:

>>>

>>> parser = argparse.ArgumentParser(prog='doors.py')

>>> parser.add_argument('door', type=int, choices=range(1, 4))

>>> print(parser.parse_args(['3']))

Namespace(door=3)

>>> parser.parse_args(['4'])

usage: doors.py [-h] {1,2,3}

doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

Any container can be passed as the choices value, so list objects, set objects, and custom containers
are all supported.

Use of enum.Enum is not recommended because it is difficult to control its appearance in usage,
help, and error messages.

Formatted choices overrides the default metavar which is normally derived from dest. This is usually
what you want because the user never sees the dest parameter. If this display isn’t desirable
(perhaps because there are many choices), just specify an explicit metavar.