Python argparse
last modified July 8, 2023
Python argparse tutorial shows how to parse command line arguments in Python with argparse module.
Python argparse
The argparse
module makes it easy to write user-friendly
command-line interfaces. It parses the defined arguments from the
sys.argv
.
The argparse
module also automatically generates help and usage
messages, and issues errors when users give the program invalid arguments.
The argparse
is a standard module; we do not need to install it.
A parser is created with ArgumentParser
and a new parameter is
added with add_argument
. Arguments can be optional, required, or
positional.
Python argparse optional argument
The following example creates a simple argument parser.
#!/usr/bin/python import argparse # help flag provides flag help # store_true actions stores argument as True parser = argparse.ArgumentParser() parser.add_argument('-o', '--output', action='store_true', help="shows output") args = parser.parse_args() if args.output: print("This is some output")
The example adds one argument having two options: a short -o
and
a long --ouput
. These are optional arguments.
import argparse
The module is imported.
parser.add_argument('-o', '--output', action='store_true', help="shows output")
An argument is added with add_argument
. The action
set to store_true
will store the argument as True
, if present.
The help option gives argument help.
args = parser.parse_args()
The arguments are parsed with parse_args
. The parsed arguments are
present as object attributes. In our case, there will be
args.output
attribute.
if args.output: print("This is some output")
If the argument is present, we show some output.
$ optional_arg.py -o This is some output $ optional_arg.py --output This is some output
We run the program with the -o
and --output
.
$ optional_arg.py --help usage: optional_arg.py [-h] [-o] optional arguments: -h, --help show this help message and exit -o, --output shows output
We can show the program help.
Python argparse required argument
An argument is made required with the required
option.
#!/usr/bin/python import argparse # required arg parser = argparse.ArgumentParser() parser.add_argument('--name', required=True) args = parser.parse_args() print(f'Hello {args.name}')
The example must have the name
option specified; otherwise
it fails.
$ required_arg.py --name Peter Hello Peter $ required_arg.py usage: required_arg.py [-h] --name NAME required_arg.py: error: the following arguments are required: --name
Python argparse positional arguments
The following example works with positional arguments. They are created with
add_argument
.
#!/usr/bin/python import argparse # positional args parser = argparse.ArgumentParser() parser.add_argument('name') parser.add_argument('age') args = parser.parse_args() print(f'{args.name} is {args.age} years old')
The example expects two positional arguments: name and age.
parser.add_argument('name') parser.add_argument('age')
Positional arguments are created without the dash prefix characters.
$ positional_arg.py Peter 23 Peter is 23 years old
Python argparse dest
The dest
option of the add_argument
gives
a name to the argument. If not given, it is inferred from the option.
#!/usr/bin/python import argparse import datetime # dest gives a different name to a flag parser = argparse.ArgumentParser() parser.add_argument('-n', dest='now', action='store_true', help="shows now") args = parser.parse_args() # we can refer to the flag # by a new name if args.now: now = datetime.datetime.now() print(f"Now: {now}")
The program gives the now
name to the -n
argument.
$ ./dest.py -n Now: 2022-08-20 09:42:32.195881
Python argparse type
The type
argument determines the argument type.
#!/usr/bin/python import argparse import random # type determines the type of the argument parser = argparse.ArgumentParser() parser.add_argument('-n', type=int, required=True, help="define the number of random integers") args = parser.parse_args() n = args.n for i in range(n): print(random.randint(-100, 100))
The program shows n random integers from -100 to 100.
parser.add_argument('-n', type=int, required=True, help="define the number of random integers")
The -n
option expects integer value and it is
required.
$ rand_int.py -n 3 92 -61 -61
Python argparse default
The default
option specifies the default value,
if the value is not given.
#!/usr/bin/python import argparse # required defines a mandatory argument # default defines a default value if not specified parser = argparse.ArgumentParser() parser.add_argument('-b', type=int, required=True, help="defines the base value") parser.add_argument('-e', type=int, default=2, help="defines the exponent value") args = parser.parse_args() val = 1 base = args.b exp = args.e for i in range(exp): val *= base print(val)
The example computes exponentiation. The exponent value is not required; if not given, the default will be 2.
$ power.py -b 3 9 $ power.py -b 3 -e 3 27
Python argparse metavar
The metavar
option gives a name to the
expected value in error and help outputs.
#!/usr/bin/python import argparse # metavar gives name to the expected value # in error and help outputs parser = argparse.ArgumentParser() parser.add_argument('-v', type=int, required=True, metavar='value', help="computes cube for the given value") args = parser.parse_args() print(args) val = args.v print(val * val * val)
The example names the expected value value
. The default
name is V
.
$ metavar.py -h usage: metavar.py [-h] -v value optional arguments: -h, --help show this help message and exit -v value computes cube for the given value
The given name is shown in the help output.
Python argparse append action
The append
action allows to group repeating options.
#!/usr/bin/python import argparse # append action allows to group repeating # options parser = argparse.ArgumentParser() parser.add_argument('-n', '--name', dest='names', action='append', help="provides names to greet") args = parser.parse_args() names = args.names for name in names: print(f'Hello {name}!')
The example produces greeting messages to all names specified with the
n
or name
options; they can be repeated multipile
times.
$ appending.py -n Peter -n Lucy --name Jane Hello Peter! Hello Lucy! Hello Jane!
Python argparse nargs
The nargs
specifies the number of command-line arguments that
should be consumed.
#!/usr/bin/python import argparse import sys # nargs sets the required number of argument values # metavar gives name to argument values in error and help output parser = argparse.ArgumentParser() parser.add_argument('chars', type=str, nargs=2, metavar='c', help='starting and ending character') args = parser.parse_args() try: v1 = ord(args.chars[0]) v2 = ord(args.chars[1]) except TypeError as e: print('Error: arguments must be characters') parser.print_help() sys.exit(1) if v1 > v2: print('first letter must precede the second in alphabet') parser.print_help() sys.exit(1)
The example shows a sequence of characters from character one to character two. It expects two arguments.
parser.add_argument('chars', type=str, nargs=2, metavar='c', help='starting and ending character')
With nargs=2
we specify that we expect two arguments.
$ charseq.py e k e f g h i j k
The program shows a sequence of characters from e to k.
Variable number of arguments can be set with the *
character.
#!/usr/bin/python import argparse # * nargs expects 0 or more arguments parser = argparse.ArgumentParser() parser.add_argument('num', type=int, nargs='*') args = parser.parse_args() print(f"The sum of values is {sum(args.num)}")
The example computes the sum of values; we can specify variable number of arguments to the program.
$ var_args.py 1 2 3 4 5 The sum of values is 15
Python argparse choices
The choices
option limits arguments
to the given list.
#!/usr/bin/python import argparse import datetime import time # choices limits argument values to the # given list parser = argparse.ArgumentParser() parser.add_argument('--now', dest='format', choices=['std', 'iso', 'unix', 'tz'], help="shows datetime in given format") args = parser.parse_args() fmt = args.format if fmt == 'std': print(datetime.date.today()) elif fmt == 'iso': print(datetime.datetime.now().isoformat()) elif fmt == 'unix': print(time.time()) elif fmt == 'tz': print(datetime.datetime.now(datetime.timezone.utc))
In the example, the now
option can accept the following
values: std
, iso
, unix
, or tz
.
$ ./mytime.py --now iso 2022-08-20T09:44:22.437880 $ ./mytime.py --now unix 1660981466.8261166
Head example
The following example mimics the Linux head command. It shows the n lines of a text from the beginning of the file.
sky top forest wood lake wood
For the example, we have this small test file.
#!/usr/bin/python import argparse from pathlib import Path # head command # working with positional arguments parser = argparse.ArgumentParser() parser.add_argument('f', type=str, help='file name') parser.add_argument('n', type=int, help='show n lines from the top') args = parser.parse_args() filename = args.f lines = Path(filename).read_text().splitlines() for line in lines[:args.n]: print(line)
The example has two options: f
for a file name and
-n
for the number of lines to show.
$ head.py words.txt 3 sky top forest
In this tutorial we have worked with Python argparse module.
Author
List all Python tutorials.