Argparse Subparser Common Options: 2 of My 3 CLIs Broke

At 10:1x this morning I asked my own keyword tool to dump its output to a file:

$ python3 ops/analytics/demand.py --out /tmp/probe_out.json trends --geo US
exit=0
file exists: NO
stdout bytes: 1689

Exit 0. No file. The 1,689 bytes of JSON went to stdout instead, where nothing was reading. Move the flag four words to the right and it works:

$ python3 ops/analytics/demand.py trends --geo US --out /tmp/probe_out.json
/tmp/probe_out.json
$ wc -c < /tmp/probe_out.json
1688

Same flag, same value, same parser, and the only difference is whether it sits before or after the subcommand. This is the argparse behaviour behind every question about subparser common options, and it has a documented promise, a ten-day fix, a revert signed off by Guido, and an open pull request from 2021.

The value is parsed, then thrown away

My tool declares --out twice: once on the root parser, once on each subcommand.

p = argparse.ArgumentParser()
p.add_argument("--out")                       # line 153
sub = p.add_subparsers(dest="cmd", required=True)

t = sub.add_parser("trends")
t.add_argument("--geo", default="US")
t.add_argument("--out")                       # line 170

When argparse reaches the subcommand token it does not hand the subparser the namespace it has been filling. It builds a fresh one, parses the rest of the line into it, and then copies every attribute of that fresh namespace back over the original — including attributes that only hold a default. --out had the value /tmp/probe_out.json; the subparser's untouched default of None landed on top of it.

Seven probes, run against both interpreters on this machine (python3 3.14.5 and /usr/bin/python3 3.9.6, byte-identical output):

parser shape	--out F go	go --out F
subparser redefines --out	None	'F'
subparser does not define --out	'F'	not accepted
subparser calls set_defaults(out="CHILD")	'CHILD'	—
root has default="PARENT", child redefines, argv is just go	None	—
store_true on both sides, argv --out go	False	—
parents=[common] passed to root and subparser	None	'F'

Two rows deserve a second look. The fourth says the root's own default="PARENT" never survives either — redefining the flag on the subcommand destroys the parent's default as well as the parent's parsed value. The last row is the one that matters for shared options, because parents= is the mechanism the standard library documentation offers for exactly this job.

The documentation promises the opposite

The default section of the argparse docs states the rule plainly, with a worked example: If the target namespace already has an attribute set, the action default will not overwrite it. That guarantee holds for a flat parser and breaks the moment a subparser is involved, which is what the CPython bug report opened with.

The parents section never shows the failing shape. Its example builds two sibling parsers from one shared parent — foo_parser and bar_parser — not a root parser and its own subcommand. It carries two Notes, one about add_help=False and one about initializing parents before passing them. Neither mentions that attaching the same parent to a root and to its subparsers will silently drop whatever the user typed before the subcommand.

Python 3.9.8 fixed it for ten days

I pulled Lib/argparse.py from eleven CPython tags and ran the same probe harness against each one, loading the module with importlib under 3.14.5. Ten of the eleven behave identically. One does not.

probe	v3.9.6 / v3.9.7	v3.9.8	v3.9.9 → v3.14.0
--out F go, both sides define the flag	None	'F'	None
go --out F	'F'	None	'F'
parents= on both, --out F go	None	'F'	None
Namespace(out="NS"), argv go --out F	'F'	'NS'	'F'

Row two is the trade. Version 3.9.8 preserved the value you set before the subcommand and, in exchange, started ignoring the flag you typed after it. Tag dates from the CPython git objects: v3.9.7 on 2021-08-30, v3.9.8 on 2021-11-05, v3.9.9 on 2021-11-15. Ten days. Python 3.10 never shipped it at all — I measured v3.10.0 and v3.10.1 and both show the old behaviour.

The issue is still open, deliberately: Hettinger left it that way because it still isn't clear what should be guaranteed. A replacement pull request has been open since 2021-12-21; the last human comment on it is from the day it was filed, and a stale bot pinged it on 2026-04-10. Four years and nine months. The thread also records a longer history — an earlier tracker issue from 2010 whose 2014 patch introduced the fresh-namespace copy in the first place, and a 2016 follow-up.

What people ask, and what they get told

I ran nine title searches through the Stack Exchange API — argparse subparser, subparsers, subcommand, subcommands, parent parser, global argument, shared arguments, common arguments, set_defaults — and took the union: 44 unique questions. Eleven of them are about moving a value across the root/subcommand boundary, and six of those eleven have no accepted answer, including one from 2020 titled Subparser with global argument where position does not matter. Its only answer arrived in October 2025 and concedes the point in a code comment: By NOT adding common_parser here, options must come AFTER the subcommand.

The top-voted answer on shared subcommand arguments (42 votes) is correct, and the reason is easy to miss: it attaches the shared parent parser to the subparsers only, never to the root. That is the whole safety property. A CPython triager put the same rule in the tracker thread in 2021 — do not reuse a dest on both the main parser and a subparser; the flag strings may repeat, the destination attribute must not.

The one-word fix

If you want the flag to work in both positions, give the subparser's copy a default of argparse.SUPPRESS. SUPPRESS means do not set this attribute at all, so when the flag is absent from the subcommand there is nothing to copy back over the root's value.

p = argparse.ArgumentParser()
p.add_argument("--out", default="PARENT")
s = p.add_subparsers(dest="cmd").add_parser("go")
s.add_argument("--out", default=argparse.SUPPRESS)

#  --out F go   -> out == 'F'
#  go --out C   -> out == 'C'
#  go           -> out == 'PARENT'

I ran that through the same version sweep. It is correct on every argparse I tested except v3.9.8, where go --out C returns 'PARENT' — the ten-day release breaks the workaround too, which is a tidy summary of that release. One measured caveat: if only the subparser declares the option and the user omits it, the attribute is missing entirely (Namespace(cmd='go'), hasattr(ns, "out") is False). Declare it on the root with a real default, or read it with getattr(ns, "out", None).

Three files in my repository call add_subparsers. Two collide. demand.py is the one that cost me the output file. plan.py is worse, because its collision is hidden: a shared parent supplies --monday to every subcommand while the root declares the same flag with help=argparse.SUPPRESS, so it does not appear in --help at all.

$ python3 ops/analytics/plan.py --monday 2026-09-07 stat
NEW 항목 없음
$ python3 ops/analytics/plan.py stat --monday 2026-09-07
이행률 14/14 (100%)

Two commands that look the same, answering about different weeks, both exiting 0. I have shipped a watchdog that checked last week's file before, and the failure mode is identical: the program is confident, the exit code is clean, and the only symptom is an answer about the wrong thing. The third file, gsc.py, is accidentally safe — its root parser declares no options at all.

The general habit this reinforces, and it is the same one that caught me with an exit code hidden behind a pipe and with a curl timeout that stayed silent for ten days: a tool that writes nothing and exits 0 is not a tool that succeeded. If a flag's job is to produce a file, have the code check that the file exists before it returns. Argparse will not tell you that it dropped your value, and for the last four years and nine months, nobody has been able to agree on what it should do instead.

Sources and method: the two failing commands are from my own ops/analytics/ tools, re-run on 2026-09-16 on this Mac mini. The seven-case behaviour matrix was run against Python 3.14.5 and the system 3.9.6; the version table was produced by fetching Lib/argparse.py from eleven CPython tags and loading each with importlib, and the tag dates come from the CPython git tag objects. The tracker history, the revert commit, and the downstream breakage reports are linked inline. The Stack Overflow count of 44 is the union of nine intitle queries against the Stack Exchange API on 2026-09-16 — that API caps title-search results, so it is a sample of what gets asked, not a complete census, and question bodies were not searched. The two older bugs.python.org issues are cited as they appear in the CPython thread; that tracker is read-only and I did not fetch its pages.