Use store_true for a single switch that turns a feature on, store_false for a single switch that turns it off, and BooleanOptionalAction when users should see both positive and negative forms of the same setting. These actions take no true or false value after the option. Their defaults and Python version requirements determine which interface is appropriate.
Choose by the command users should type
If the normal state is disabled, a positive --enabled switch with action='store_true' is direct: omission yields False and presence yields True. For an option named --disable-cache, action='store_true' would set disable_cache to True, which may be exactly what the program needs, although the stored name describes disabling rather than cache state. Choose the destination and help wording so the value has a clear meaning.
If the normal state is enabled and one switch should turn it off, use a negative name such as --no-cache with action='store_false', optionally setting dest='cache'. Omission then gives cache=True and presence gives cache=False. This is useful when only the disabling operation needs a command-line spelling.
Sources: argparse — Parser for command-line options, arguments and subcommands — action; dest
Compare the three interfaces
BooleanOptionalAction suits a setting users may deliberately enable or disable on separate invocations. Adding --cache creates --cache and --no-cache, which store True and False. The documented class was added in Python 3.9, so choose another interface when supporting older Python versions. Unlike the two store actions, its documented default is not an opposite boolean; specify default=True or default=False when the application has a settled starting state.
This table assumes the declarations shown and no parser-wide override. It compares the resulting cache attribute so the choice is about user-facing syntax and omitted-option meaning, not about different variable names.
| Declaration | Omitted | Accepted flag and result |
|---|---|---|
| add_argument('--cache', action='store_true') | False | --cache gives True |
| add_argument('--no-cache', dest='cache', action='store_false') | True | --no-cache gives False |
| add_argument('--cache', action=argparse.BooleanOptionalAction, default=None) | None | --cache gives True; --no-cache gives False |
Sources: argparse — Parser for command-line options, arguments and subcommands — action; default; class argparse.BooleanOptionalAction
Set omission and conflict rules deliberately
A flag is complete by itself. Supplying --cache false to one of these declarations does not convert false into a boolean; with no other positional argument to receive it, parse_args reports an unrecognized argument. If callers must pass a text value after --cache, use the strict converter in the companion article instead.
Pick an omitted-option value for the application, not merely for convenience. A boolean default says what happens when the user says nothing. A None default can preserve the distinction between no command-line preference and an explicit positive or negative choice, which is useful when a later configuration source supplies the baseline. If both directions are exposed with BooleanOptionalAction, decide how the application should handle both forms in one invocation; for an interface that must reject conflicting choices, define separate options inside a mutually exclusive group. Argparse documents that such a group rejects simultaneous options. Review the generated help so users can see the accepted spelling and the effect of omission.
Sources: argparse — Parser for command-line options, arguments and subcommands — default; class argparse.BooleanOptionalAction; Mutual exclusion, Argparse Tutorial — Introducing Optional arguments
Primary sources checked: 2026-11-02. Prepared with AI assistance and a separate evidence review. This is documentation-based guidance, not a hands-on test or performance benchmark.
