Introduction

In argparse, a default value is used only when the option is omitted. If the user supplies the option, the supplied value wins. The real design question is often whether you need a simple default, or whether you also need to know whether the user explicitly provided the argument.

Basic Default Behavior

A normal default is straightforward.

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("--port", type=int, default=8080)
5args = parser.parse_args()
6
7print(args.port)

Behavior:

• no --port means the result is 8080
• '--port 5000 means the result is 5000'

This is the standard “default or specified value” behavior.

Use None When You Need to Detect Omission

Sometimes the program needs to know whether the user omitted the argument entirely. In that case, using a sentinel such as None is often enough.

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("--port", type=int, default=None)
5args = parser.parse_args()
6
7if args.port is None:
8    print("user did not provide --port")
9else:
10    print(f"user chose {args.port}")

This is useful when the real default comes from another source such as a config file or environment variable.

Combining CLI, Environment, and Hard Defaults

A common pattern is:

1. command-line argument if provided
2. environment variable if present
3. hardcoded fallback if neither exists

1import argparse
2import os
3
4parser = argparse.ArgumentParser()
5parser.add_argument("--port", type=int, default=None)
6args = parser.parse_args()
7
8port = args.port
9if port is None:
10    env_port = os.getenv("APP_PORT")
11    port = int(env_port) if env_port else 8080
12
13print(port)

This keeps argparse simple while still supporting layered configuration.

argparse.SUPPRESS for Advanced Cases

If you want omitted arguments to be absent from the namespace entirely, use argparse.SUPPRESS.

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("--port", type=int, default=argparse.SUPPRESS)
5args = parser.parse_args()
6
7if hasattr(args, "port"):
8    print(f"user provided {args.port}")
9else:
10    print("no --port argument was given")

This is more explicit than None when None could itself be a meaningful value in your application logic.

Boolean Flags Are Different

Boolean flags often use actions such as store_true or store_false, which change how defaults work.

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

Here the default is False, and specifying --verbose sets it to True. That is still default-versus-specified behavior, but through an action rather than a typed value.

Common Pitfalls

Make Defaults Visible To Users

If a command-line option has an important fallback value, reflect that in the help text or documentation so callers are not surprised by hidden defaults at runtime.

Positional Arguments Follow Different Rules

Defaults for optional flags are common, but positional arguments behave differently because they are usually required unless you explicitly configure nargs or other parsing behavior. That distinction matters when you mix mandatory positional input with optional overrides in one CLI.

The most common mistake is setting a concrete default too early when the real value should come from a later configuration layer such as environment or file settings.

Another mistake is using None as a sentinel without checking whether None could also be a meaningful business value.

Developers also often forget that boolean flags use action-based behavior rather than ordinary typed defaults. For complex CLIs, it is often clearer to keep parsing simple and apply higher-level fallback rules after parse_args() returns. That keeps precedence rules visible in one place instead of hiding them inside parser defaults.

Summary

• 'argparse uses the default only when the option is omitted.'
• A provided command-line value always overrides the default.
• Use None or argparse.SUPPRESS when you need to detect whether the user specified the option.
• Layer command-line, environment, and hardcoded defaults deliberately.
• Treat boolean flags as a slightly different case because they use actions.