optparse

Key Features

• Declarative option definitions using add_option()
• Built-in option types such as string, int, float, and choice
• Automatic generation of usage and help messages
• Configurable actions including store, store_true, store_false, append, and count
• Support for option groups that organize related flags in the help output
• Custom callbacks that run when an option is encountered
• Error reporting that prints a usage message and exits the program

Frequently Used Classes and Functions

Examples

Define a boolean flag that flips a default-True value to False when the option is supplied:

>>> import optparse

>>> parser = optparse.OptionParser()
>>> parser.add_option(
...     "-q",
...     "--quiet",
...     action="store_false",
...     dest="verbose",
...     default=True
... )
<Option at 0x...: -q/--quiet>

>>> options, args = parser.parse_args(["-q"])
>>> options.verbose
False

Use a typed option with a restricted set of choices:

>>> import optparse

>>> parser = optparse.OptionParser()
>>> parser.add_option(
...     "-c",
...     "--color",
...     type="choice",
...     choices=["red", "green", "blue"]
... )
<Option at 0x...: -c/--color>

>>> options, args = parser.parse_args(["-c", "green"])
>>> options.color
'green'

Read an integer option with a default value:

>>> import optparse

>>> parser = optparse.OptionParser()
>>> parser.add_option(
...     "-n",
...     "--lines",
...     type="int",
...     default=10
... )
<Option at 0x...: -n/--lines>

>>> options, args = parser.parse_args(["-n", "25"])
>>> options.lines
25

Common Use Cases

The most common tasks for optparse include:

• Maintaining legacy command-line tools that already depend on optparse
• Building scripts that need precise control over how options and positional arguments are interleaved
• Parsing options whose values may begin with a dash, such as flags forwarded to a subprocess
• Providing a lower-level foundation for third-party argument parsing libraries
• Porting existing code incrementally before migrating to argparse

Real-World Example

Consider a small script that counts lines in a file, with flags for the input path and verbose output:

import optparse

def parse_args():
    parser = optparse.OptionParser(
        usage="usage: %prog [options] -f FILE"
    )
    parser.add_option(
        "-f",
        "--file",
        dest="filename",
        help="input file to read",
        metavar="FILE",
    )
    parser.add_option(
        "-v",
        "--verbose",
        action="store_true",
        dest="verbose",
        default=False,
        help="print extra diagnostic output",
    )
    options, _ = parser.parse_args()

    if options.filename is None:
        parser.error("the -f/--file option is required")

    return options

def main():
    options = parse_args()

    with open(options.filename) as source:
        count = sum(1 for _ in source)

    if options.verbose:
        print(f"Counted {count} lines in {options.filename}")
    else:
        print(count)

if __name__ == "__main__":
    main()

Run it on the command line:

$ python count_lines.py -f data.txt -v
Counted 42 lines in data.txt

Splitting parse_args() from main() keeps the option-handling logic separate from the line-counting work. The parser validates the flags, reports a friendly error when -f is missing, and exposes the parsed values as attributes on the options object that main() can then consume.

Related Resources

Tutorial

Build Command-Line Interfaces With Python's argparse

In this step-by-step Python tutorial, you'll learn how to take your command-line Python scripts to the next level by adding a convenient command-line interface (CLI) that you can write with the argparse module from the standard library.

intermediate python stdlib

For additional information on related topics, take a look at the following resources:

• Click and Python: Build Extensible and Composable CLI Apps (Tutorial)
• 4 Techniques for Testing Python Command-Line (CLI) Apps (Tutorial)
• Build a Command-Line To-Do App With Python and Typer (Tutorial)
• Python Command-Line Arguments (Tutorial)
• Building Command Line Interfaces With argparse (Course)
• Build Command-Line Interfaces With Python's argparse (Quiz)
• Building a Python Command-Line To-Do App With Typer (Course)
• Command Line Interfaces in Python (Course)