argparse
argparse is Python's stdlib CLI parser. It generates --help, validates types, and supports subcommands without third-party dependencies.
Search across all documentation pages
argparse is Python's stdlib CLI parser. It generates --help, validates types, and supports subcommands without third-party dependencies.
import argparse
def main():
parser = argparse.ArgumentParser(prog="invoice", description="Manage invoices")
parser.add_argument("--format", choices=["json", "csv"], default="json")
parser.add_argument("id", type=int, nargs="?", help="Invoice ID")
args = parser.parse_args()
print(args)
if __name__ == "__main__":
main()When to reach for this:
--help and type validationimport argparse
import sys
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
prog="deploy",
description="Deploy application to environments",
)
parser.add_argument("--verbose", "-v", action="count", default=0)
sub = parser.add_subparsers(dest="env", required=True)
for name in ("staging", "production"):
p = sub.add_parser(name, help=f"Deploy to {name}")
p.add_argument("--dry-run", action="store_true")
p.add_argument("--tag", required=True, help="Docker image tag")
return parser
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv)
if args.verbose:
print(f"Deploying {args.tag} to {args.env}", file=sys.stderr)
if args.dry_run:
print("Dry run - no changes made")
return 0
# deploy logic here
return 0
if __name__ == "__main__":
raise SystemExit(main())What this demonstrates:
deploy staging / deploy productionaction="count" for -v, -vv verbosityparse_args(argv) enables testing without subprocessraise SystemExit(main()) for proper exit codes| Pattern | Code |
|---|---|
| Flag | action="store_true" |
| Optional value | nargs="?" |
| List | nargs="+" |
| Choices | choices=["a", "b"] |
| Version | action="version", version="1.0" |
required=True on subparsers - no command still runs. Fix: required=True (Python 3.7+).parse_args() without argv. Fix: pass argv list in tests.help= on every argument.--help. Fix: load secrets from env at runtime.| Alternative | Use When | Don't Use When |
|---|---|---|
| Click | Ergonomic decorators | Stdlib-only required |
| Typer | Type-hint driven | No type hints in project |
| fire | Instant CLI from any object | Production CLI quality needed |
argparse for simple, zero-dep tools. Click/Typer for complex CLIs.
parser.parse_args(["--format", "csv", "42"]).
group = parser.add_mutually_exclusive_group().
type=my_validator function that converts or raises ArgumentTypeError.
argument_default=argparse.SUPPRESS to hide, or leave default to show.
Zero or one argument. Makes positional optional.
argparse handles CLI only. Load config file separately; CLI overrides.
action=argparse.BooleanOptionalAction gives --flag / --no-flag (3.9+).
parser = argparse.ArgumentParser(epilog="Examples: ...", formatter_class=argparse.RawDescriptionHelpFormatter).
Show warning in handler; document in help as deprecated.
Stack versions: This page was written for Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.
Reviewed by Chris St. John·Last updated Jul 19, 2026