Menu
Article Python & Django

Python argparse cheat sheet

Oleg Yamnikov

• 3 min read

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:

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

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