Introduction

In argparse, an option without an argument is called a flag. Instead of consuming a value such as --port 8080, the flag changes program behavior simply by being present. The normal way to define one is with an action such as store_true or store_false.

Use store_true for a Simple Flag

If you want --verbose to mean "turn verbose mode on," use action="store_true".

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("--verbose", action="store_true")
5args = parser.parse_args()
6
7print(args.verbose)

Now:

python app.py

prints False, while:

python app.py --verbose

prints True.

The option does not need any extra argument because the presence of the flag itself is the signal.

Use store_false for the Reverse Meaning

Sometimes the default should be True and the flag should turn something off.

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("--no-cache", dest="use_cache", action="store_false")
5parser.set_defaults(use_cache=True)
6args = parser.parse_args()
7
8print(args.use_cache)

With no flag, use_cache is True. If --no-cache is present, it becomes False.

This pattern is clearer than forcing users to type --cache false.

Use BooleanOptionalAction for Paired Flags

Modern Python also supports a paired boolean style through BooleanOptionalAction.

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("--feature", action=argparse.BooleanOptionalAction)
5args = parser.parse_args()
6
7print(args.feature)

This automatically gives you both:

• '--feature'
• '--no-feature'

That is useful when you want symmetrical on and off flags without defining two separate arguments manually.

Count Repeated Flags When Needed

Some CLIs use repeated flags such as -v or -vv to increase verbosity. In that case, use count.

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("-v", "--verbose", action="count", default=0)
5args = parser.parse_args()
6
7print(args.verbose)

Examples:

python app.py          # 0
python app.py -v       # 1
python app.py -vv      # 2

This is still an option without a separate argument, but it gives you more than a simple boolean.

Do Not Use type=bool for Flags

A common beginner mistake is writing something like this:

parser.add_argument("--verbose", type=bool)

That means the option expects a value, which is a different interface.

python app.py --verbose true

If your goal is a presence-based switch, use action, not type=bool.

A Practical Example

1import argparse
2
3parser = argparse.ArgumentParser(description="Backup tool")
4parser.add_argument("source")
5parser.add_argument("--dry-run", action="store_true", help="Show actions without writing changes")
6parser.add_argument("--no-color", dest="color", action="store_false", help="Disable colored output")
7parser.set_defaults(color=True)
8
9args = parser.parse_args()
10print(args)

This produces a clean, typical CLI design where flags describe behavior and positional arguments describe required input.

Short Flags and Long Flags Together

Many CLIs expose both a short form and a long form for the same flag. argparse supports that naturally.

parser.add_argument("-q", "--quiet", action="store_true")

This lets users choose whichever form fits the situation:

• '-q for quick terminal use'
• '--quiet for readability in scripts and documentation'

That small design choice makes a CLI easier to use without changing the parsing model at all.

Common Pitfalls

The most common mistake is defining a flag with type=bool and then wondering why argparse expects an additional argument.

Another issue is choosing confusing names such as --disable-no-cache, which makes the resulting boolean hard to reason about.

Developers also sometimes forget the default value implied by store_true and store_false. Read the resulting attribute name carefully so the boolean is easy to understand later in the code.

Finally, if you want both --feature and --no-feature, do not hand-roll awkward parsing logic when BooleanOptionalAction already matches that use case.

Summary

• Use action="store_true" for a flag that turns something on.
• Use action="store_false" for a flag that turns something off.
• Use BooleanOptionalAction when you want paired on and off flags.
• Use action="count" for repeated flags such as -vv.
• Do not use type=bool when the option should not take an argument.