This is a cheat sheet designed to be quickly copied and pasted into your code. It can be especially useful to populate the add_arguments
method in custom Django management commands.
Official docs:

Basic argparse usage
import argparse
parser = argparse.ArgumentParser(
description='Performs some useful work.',
)
# Put your add_argument calls here
# parser.add_argument(...)
args = parser.parse_args()
print(args.arg)
print(args.some_param)
In the examples below, make sure to edit the argument name (instead of arg
), default
, help
and metavar
.
cmd arg
- a single positional argument
parser.add_argument(
'arg',
type=str,
default='arg_default',
nargs='?',
help='a positional argument',
metavar='ARG',
)
args = parser.parse_args([]) # Namespace(arg='arg_default')
args = parser.parse_args(['value']) # Namespace(arg='value')
type
can be changed to int
, float
, Decimal
etc.
If it's required:
parser.add_argument(
'arg',
type=str,
help='a positional argument',
metavar='ARG',
)
args = parser.parse_args([]) # Error
args = parser.parse_args(['value']) # Namespace(arg='value')
cmd arg1 arg2 arg3
- a list of positional arguments
parser.add_argument(
'arg',
type=str,
help='a list of arguments',
nargs='*',
metavar='ARG',
)
args = parser.parse_args([]) # Namespace(arg=[])
args = parser.parse_args(['val1', 'val2', 'val3']) # Namespace(arg=['val1', 'val2', 'val3'])
type
can be changed to int
, float
, Decimal
etc.
If at least 1 value is required:
parser.add_argument(
'arg',
type=str,
help='a list of string arguments',
nargs='+',
metavar='ARG',
)
args = parser.parse_args([]) # Error
args = parser.parse_args(['val1', 'val2', 'val3']) # Namespace(arg=['val1', 'val2', 'val3'])
cmd --bool-flag
parser.add_argument(
'--bool-flag', '-b',
action='store_true',
help='a simple boolean flag',
)
args = parser.parse_args([]) # Namespace(bool_flag=False)
args = parser.parse_args(['--bool-flag']) # Namespace(bool_flag=True)
args = parser.parse_args(['-b']) # Namespace(bool_flag=True)
cmd --some-param value
parser.add_argument(
'--some-param', '-p',
type=str,
default='param_default',
help='a parameter',
metavar='PARAM',
)
args = parser.parse_args(['--some-param', 'value']) # Namespace(some_param='value')
args = parser.parse_args(['--some-param=value']) # Namespace(some_param='value')
args = parser.parse_args(['-p', 'value']) # Namespace(some_param='value')
args = parser.parse_args(['-p=value']) # Namespace(some_param='value')
args = parser.parse_args([]) # Namespace(some_param='param_default')
type
can be changed to int
, float
, Decimal
etc.
If it's required:
parser.add_argument(
'--some-param', '-p',
type=str,
required=True,
help='a parameter',
metavar='PARAM',
)
args = parser.parse_args([]) # Error
cmd -p val1 -p val2 -p val3
- a list of parameter values
parser.add_argument(
'--some-param', '-p',
type=str,
action='append',
default=[],
help='a parameter',
metavar='PARAM',
)
args = parser.parse_args(['--some-param', 'val1', '--some-param', 'val2', '--some-param', 'val3'])
# Namespace(some_param=['val1', 'val2', 'val3'])
args = parser.parse_args(['-p', 'val1', '-p', 'val2', '-p', 'val3'])
# Namespace(some_param=['val1', 'val2', 'val3'])
args = parser.parse_args([]) # Namespace(some_param=[])
type
can be changed to int
, float
, Decimal
etc.
If at least 1 value is required:
parser.add_argument(
'--some-param', '-p',
type=str,
action='append',
required=True,
help='a parameter',
metavar='PARAM',
)
args = parser.parse_args(['-p', 'val1', '-p', 'val2', '-p', 'val3'])
# Namespace(some_param=['val1', 'val2', 'val3'])
args = parser.parse_args([]) # Error
cmd -p val1 val2 val3
- a list of values in a parameter
Requires Python 3.8+.
parser.add_argument(
'--some-param', '-p',
action='extend',
default=[],
type=str,
nargs="+",
help='a parameter',
metavar='PARAM',
)
args = parser.parse_args(['--some-param', 'val1', '-p', 'val2', '-p', 'val3']) # Namespace(some_param=['val1', 'val2', 'val3'])
args = parser.parse_args(['-p', 'val1', 'val2', 'val3']) # Namespace(some_param=['val1', 'val2', 'val3'])
args = parser.parse_args([]) # Namespace(some_param=[])
type
can be changed to int
, float
, Decimal
etc.
If at least 1 value is required:
parser.add_argument(
'--some-param', '-p',
action='extend',
required=True,
type=str,
nargs="+",
help='a parameter',
metavar='PARAM',
)
args = parser.parse_args(['-p', 'val1', 'val2', 'val3']) # Namespace(some_param=['val1', 'val2', 'val3'])
args = parser.parse_args([]) # Error
cmd -vvv
- count the number of occurrences
parser.add_argument(
'--verbose', '-v',
action='count',
default=0,
help='verbosity level',
)
args = parser.parse_args(['-v']) # Namespace(verbose=1)
args = parser.parse_args(['-vvv']) # Namespace(verbose=3)
args = parser.parse_args([]) # Namespace(verbose=0)
Restricting valid values
Almost all of the add_argument
calls above support the choices
parameter. You can pass an iterable through it to restrict which values the user can enter.
An example of using choices
with a positional argument:
parser.add_argument(
'dir',
type=str,
default='north',
choices=['north', 'west', 'south', 'east'],
nargs='?',
help='a direction',
metavar='DIR',
)
args = parser.parse_args(['east']) # Namespace(dir='east')
args = parser.parse_args(['up']) # Error
Subcommands
parser.set_defaults(cmd=None)
# Common parameters
parser.add_argument(
'--verbose', '-v',
default=0,
action='count',
help='verbosity level',
)
subparsers = parser.add_subparsers(help="sub-command")
# Define command A
cmda_parser = subparsers.add_parser(
'cmda',
aliases=['ca'],
help='perform task A',
)
cmda_parser.set_defaults(cmd='cmda')
# Arguments for the cmda command
cmda_parser.add_argument('cmda_arg', nargs='?')
# Define command B
cmdb_parser = subparsers.add_parser(
'cmdb',
aliases=['cb'],
help='perform task B',
)
cmdb_parser.set_defaults(cmd='cmdb')
# Arguments for the cmdb command
cmdb_parser.add_argument('cmda_arg', nargs='?')
Examples:
args = parser.parse_args([]) # Namespace(cmd=None, verbose=0)
args = parser.parse_args(['-vv']) # Namespace(cmd=None, verbose=2)
args = parser.parse_args(['cmda']) # Namespace(cmd='cmda', cmda_arg=None, verbose=0)
args = parser.parse_args(['-vvv', 'cmda']) # Namespace(cmd='cmda', cmda_arg=None, verbose=3)
args = parser.parse_args(['cmda', 'value']) # Namespace(cmd='cmda', cmda_arg='value', verbose=0)
args = parser.parse_args(['ca', 'value']) # Namespace(cmd='cmda', cmda_arg='value', verbose=0)