Introduction

argparse is Python's built-in module for parsing command-line arguments. It lets your script accept inputs from the terminal — positional arguments, optional flags, and typed values — while automatically generating help messages, validating input, and producing clean error messages. Instead of manually reading sys.argv and writing fragile parsing logic, argparse gives you a robust, self-documenting CLI with just a few lines of code.

Real-World Analogy

Prerequisites

The Problem It Solves

Reading sys.argv manually is error-prone and lacks validation or help text.

import sys

# Manual parsing — fragile and unfriendly
name = sys.argv[1]          # crashes if missing
age = int(sys.argv[2])      # no validation, cryptic errors
print(name, age)

Your First Parser

The three core steps: create a parser, add arguments, then parse them.

import argparse

# 1. Create the parser
parser = argparse.ArgumentParser(description="Greet a user")

# 2. Add arguments
parser.add_argument("name", help="the user's name")
parser.add_argument("--age", type=int, help="the user's age")

# 3. Parse the command line
args = parser.parse_args()

print(f"Hello {args.name}!")
if args.age:
    print(f"You are {args.age} years old.")

$ python greet.py Rumman --age 30
Hello Rumman!
You are 30 years old.

$ python greet.py --help
usage: greet.py [-h] [--age AGE] name
...

Positional vs Optional Arguments

Key add_argument Parameters

Boolean Flags with store_true

Use action="store_true" for on/off switches that need no value.

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--verbose", action="store_true", help="enable verbose output")
args = parser.parse_args()

if args.verbose:
    print("Verbose mode ON")

$ python app.py --verbose
Verbose mode ON

$ python app.py
# (nothing — verbose defaults to False)

Types, Defaults, and Choices

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--count", type=int, default=1, help="number of times")
parser.add_argument(
    "--mode",
    choices=["fast", "slow", "auto"],   # only these are allowed
    default="auto",
)
args = parser.parse_args()

print(args.count, args.mode)

Multiple Values with nargs

nargs controls how many values an argument accepts.

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("numbers", type=int, nargs="+", help="one or more numbers")
args = parser.parse_args()

print(sum(args.numbers))

$ python sum.py 3 5 7
15

Short and Long Option Names

Give an argument both a short (-v) and long (--verbose) form.

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("-o", "--output", help="output file path")
args = parser.parse_args()

print(args.output)   # accessed by the long name

Subcommands with add_subparsers

Build git-style CLIs (tool add, tool remove) using subparsers.

import argparse

parser = argparse.ArgumentParser(prog="tool")
subparsers = parser.add_subparsers(dest="command")

# "add" subcommand
add = subparsers.add_parser("add", help="add an item")
add.add_argument("item")

# "remove" subcommand
remove = subparsers.add_parser("remove", help="remove an item")
remove.add_argument("item")

args = parser.parse_args()

if args.command == "add":
    print(f"Adding {args.item}")
elif args.command == "remove":
    print(f"Removing {args.item}")

$ python tool.py add book
Adding book

Argument Combinations

Each boolean flag doubles the number of possible invocations. With \(f\) independent on/off flags, the number of distinct flag combinations is:

\[ N_{\text{combinations}} = 2^{f} \]

This is why clear --help text and sensible defaults matter — a handful of flags creates many possible states to reason about.

Best Practices

Common Mistakes

Interview Questions

Quick Revision