Introduction

In argparse, a positional argument can be optional, but you have to ask for that behavior explicitly with nargs. That sounds contradictory at first because "positional" describes how the argument is written on the command line, while "optional" describes whether the user is required to provide it.

Positional Versus Optional Means Two Different Things

argparse uses the word "optional" in two different everyday senses, and that causes confusion.

• A positional argument is identified by its position, for example script.py input.txt.
• An optional flag is identified by a prefix such as --verbose.
• A positional argument can still be optional in the sense that the user may omit it.

So this is a required positional argument:

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("filename")
5args = parser.parse_args()
6print(args.filename)

The user must provide a value.

Make One Positional Argument Optional With nargs='?'

If you want a single positional argument that the user may omit, use nargs='?' and usually provide a default.

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("filename", nargs="?", default="default.txt")
5args = parser.parse_args()
6print(args.filename)

Behavior:

python script.py
python script.py report.txt

The first command prints default.txt. The second prints report.txt.

This is the most common answer when someone asks for an optional positional argument in argparse.

Accept Zero Or More Positional Values With nargs='*'

If the argument can appear multiple times or not at all, use nargs='*'.

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("files", nargs="*")
5args = parser.parse_args()
6print(args.files)

Examples:

python script.py
python script.py a.txt b.txt c.txt

The result is always a list. If the user supplies nothing, it becomes an empty list.

This is useful for commands that can operate on any number of input files.

Require One Or More Values With nargs='+'

Sometimes the right design is not optionality, but variability. If the user must provide at least one positional value but may provide several, use nargs='+'.

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("files", nargs="+")
5args = parser.parse_args()
6print(args.files)

This still accepts multiple values, but unlike '*', it rejects the empty case.

Optional Positionals Need Careful Ordering

Ordering matters a lot once you mix positional arguments with optional ones. argparse can only infer so much from raw command-line tokens.

For example:

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("src")
5parser.add_argument("dst", nargs="?", default="out.txt")
6args = parser.parse_args()
7print(args)

This works well because the required positional src comes first and the optional positional dst comes last.

That pattern is much easier for both argparse and the user to understand than placing optional positional arguments in the middle of several other positional arguments.

When A Flag Is Better Than An Optional Positional

Sometimes an optional positional argument is technically possible but not the best interface. If an argument is conceptually a named setting rather than a natural ordered input, a flag is clearer.

For example, this may be harder to understand:

python script.py input.txt out.txt

Whereas this is self-documenting:

python script.py input.txt --output out.txt

And the code becomes:

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("input_file")
5parser.add_argument("--output", default="out.txt")
6args = parser.parse_args()
7print(args)

If users have to remember what the second positional value means, the interface may be too implicit.

A Good Real-World Pattern

A common CLI pattern is one required input and one optional output path.

1import argparse
2from pathlib import Path
3
4parser = argparse.ArgumentParser()
5parser.add_argument("input_file")
6parser.add_argument("output_file", nargs="?", default="result.txt")
7args = parser.parse_args()
8
9text = Path(args.input_file).read_text()
10Path(args.output_file).write_text(text.upper())

That is a legitimate use of an optional positional because the ordering is natural and the default is obvious.

Common Pitfalls

• Confusing optional positional arguments with named options such as --flag.
• Forgetting that nargs='?' returns a single value, while nargs='*' and nargs='+' return lists.
• Putting an optional positional in the middle of several other positional arguments and making parsing ambiguous.
• Skipping a sensible default when the argument is truly optional.
• Using a positional argument when a named option would make the interface clearer.

Summary

• Yes, argparse supports optional positional arguments.
• Use nargs='?' for zero or one value.
• Use nargs='*' for zero or more values.
• Keep optional positionals near the end of the positional sequence.
• Prefer named options when the meaning of the value is not obvious from position alone.