argparse vs sys.argv: Localhost Lab

Intro — what this post promises

Parse a small CLI: argparse.ArgumentParser.parse_args vs a manual sys.argv walk. This lab reports parses/s on fixed argv lists on Linux localhost.

Related links:

• 01shoppercove.comsubprocess run vs popen localhost lab
• 02shoppercove.comhmac compare digest localhost lab
• 03shoppercove.comfnmatch vs re localhost lab
• 04shoppercove.comtextwrap fill vs manual localhost lab
• 05shoppercove.comsecrets vs urandom localhost lab
• 06shoppercove.comscandir vs listdir localhost lab
• 07shoppercove.comfutures as completed vs wait localhost lab
• 08shoppercove.comshelve vs pickle dict localhost lab

Lab honesty (1 Oct 2026 IST): Python 3.13.5. Affiliates: 0. No Docker. Flags: -v/--verbose, -n/--count, -o/--output, optional path.

Verdict up front (flags argv): manual ~1539197 parses/s vs argparse reuse ~77040 (~19.98×); new parser each call ~6873. Prefer argparse for real CLIs; manual only for tiny hot wrappers.

Arms

Lab topology

20_000 parses · 7 rounds · p50
variants: minimal / short flags / long flags
also: format_help ops/s

Script: lab-evidence/97-argparse-vs-sys-argv/results/run_lab.py.

Lead table — parses/s (p50)

format_help: ~9324/s (help text generation cost).

Reading it

• Manual wins raw speed by a large margin — it skips help, types beyond int(), conflict checks, and usage formatting.
• Reuse the parser if you must call argparse in a loop (~11.21× vs rebuilding).
• CLI processes parse argv once — microseconds rarely matter versus I/O.
• Use argparse (or click/typer) when users deserve --help, validation, and subcommands.

When manual is OK

Internal wrappers with two booleans and no public help text can scan sys.argv — keep them tiny and tested. The moment you add mutual exclusion, typed options, or user-facing errors, switch to argparse.

Startup vs microbench

Real tools pay import time, logging setup, and config load far above one parse_args. This lab isolates the parser so the ~20.0× gap is visible — it is not a mandate to abandon argparse in production CLIs.

Help text is a feature

format_help ran at ~9324/s on this schema — cheap at human scale. Shipping a hand parser without --help saves nanoseconds and costs support time. Count that as argparse’s real product.

Subcommands footnote

This schema is flat flags only. Subparsers, mutually exclusive groups, and custom types widen the argparse vs manual gap further — manual clones become bug farms. That is another reason the microbench win for sys.argv should not drive public CLI design.

Typed defaults

argparse applied type=int and defaults in one call. The manual arm trusted int() on the next token — fine in a lab, brittle if users pass --count without a value. Validation belongs in the parser unless the wrapper is truly private.

Pitfalls

• Rebuilding ArgumentParser inside a hot loop.
• Hand-rolled parsers that silently ignore unknown flags.
• Optimizing parse_args before measuring the rest of startup.
• Forgetting that argparse’s product is UX + correctness, not Mops/s.

Reproduce

python3 lab-evidence/97-argparse-vs-sys-argv/results/run_lab.py

Evidence: summary.json, summary.txt.

Limits

One Linux box. One small flag schema. Not click/typer/fire. Not GNU getopt parity.

Once per process

A normal CLI parses argv once at startup. Even at argparse’s ~77k parses/s, a single parse is tens of microseconds — invisible next to importing libraries. Chase clarity first; chase parses/s only inside unusual hot loops (generated tools, fuzz harnesses).

Takeaway

On a flags argv, manual ~1539197 parses/s vs argparse ~77040. Default to argparse for CLIs; keep manual sys.argv for tiny internal wrappers — and always reuse the parser object if you parse repeatedly.