argparse

1.4.0 verified Tue May 12 auth: no python install: verified

argparse is Python's standard library module for parsing command-line arguments. It simplifies the creation of user-friendly command-line interfaces by allowing programs to define required arguments and options, automatically generating help messages, and handling argument parsing and validation. It has been part of the standard library since Python 2.7 and 3.2. The PyPI package (version 1.4.0) is a backport primarily for older Python versions (< 2.7 or < 3.2) and is currently archived.

pip install argparse

Common errors

error error: argument N: invalid int value: 'a' ↓

cause Occurs when a non-integer value is provided for an argument expected to be an integer.

fix

Ensure that all inputs for integer arguments are valid integers.

error error: unrecognized arguments: --unknown ↓

cause Happens when an argument is passed that the parser does not recognize.

fix

Verify that all provided arguments are defined in the parser and correctly spelled.

error error: the following arguments are required: --input ↓

cause Triggered when a required argument is missing from the command line input.

fix

Include all required arguments when running the program.

error error: argument --mode: invalid choice: 'fast' (choose from 'slow', 'medium') ↓

cause Occurs when an argument is given a value that is not among its predefined choices.

fix

Provide a value that is within the allowed choices for the argument.

error error: argument --count: invalid int value: 'ten' ↓

cause Happens when a non-integer string is provided for an argument that expects an integer.

fix

Ensure that the value provided for the argument is a valid integer.

Warnings

gotcha The `argparse` module is part of the Python standard library for versions 2.7 and 3.2 and later. The PyPI package `argparse` (version 1.4.0) is a backport primarily intended for older Python versions (e.g., Python < 2.7 or < 3.2) or specific older Python 3.x releases. For most modern Python users, `pip install argparse` is unnecessary and potentially problematic as you already have a built-in, possibly newer, version. ↓

fix Do not `pip install argparse` on modern Python versions; simply `import argparse`. If targeting older Python versions, explicitly install the PyPI backport.

gotcha By default, `argparse` treats all command-line inputs as strings. If you expect integer, float, or other types, you must explicitly specify the `type` argument in `add_argument()`. Failure to do so will result in string values, requiring manual conversion and validation in your code. ↓

fix Use `parser.add_argument('arg_name', type=int, help='...')` or `type=float` for automatic type conversion and basic validation.

gotcha When `argparse` encounters invalid arguments or requests for help, its default behavior is to print messages to `sys.stderr` and then exit the program using `sys.exit()`. This can be undesirable in applications where you want to handle errors programmatically or integrate argument parsing into a larger system without exiting. ↓

fix To customize this behavior, you can subclass `ArgumentParser` and override the `exit()` or `_print_message()` methods. Alternatively, for simple cases, `parser.parse_args(args=['--help'])` will still exit, but `parser.parse_known_args()` can be used to process only recognized arguments and return the rest.

deprecated The `nargs=REMAINDER` action was removed from the official documentation due to its fragility and potential for unexpected behavior when interspersed with other options. While still functional, it's not recommended for new code. ↓

fix Instead of `nargs=REMAINDER`, consider using `parser.parse_known_args()` to separate known arguments from unrecognized ones, and then process the 'unknown' arguments manually if needed.

breaking The `optparse` module, a predecessor to `argparse`, was officially deprecated in Python 2.7+ and 3.2+ in favor of `argparse`. While `optparse` is still available, `argparse` offers more features and a different API, meaning direct replacements might require code changes. ↓

fix New projects should use `argparse`. For existing `optparse` code, review the 'Upgrading Optparse Code' section in the `argparse` documentation for migration guidance, as direct compatibility is not always maintained.

gotcha If an argument value itself starts with a hyphen (e.g., a negative number or a filename like `-output.txt`), `argparse` might misinterpret it as an optional argument or flag, leading to 'unrecognized argument' errors. ↓

fix Users can typically resolve this by preceding such values with a special `--` argument, which tells `argparse` to stop processing options and treat everything that follows as positional arguments. For specific arguments, you can also adjust `parser.prefix_chars` if appropriate, or use `nargs` and a custom type if dealing with very specific formats.

gotcha When a required argument (especially positional arguments without `nargs='?'` or `default`) is not provided on the command line, `argparse` will raise an error and exit, indicating which arguments are missing. This is its intended behavior for enforcing argument presence. ↓

fix Ensure all required arguments are provided when invoking the script. For optional positional arguments, use `nargs='?'` or provide a `default` value in `add_argument()`.

gotcha When a positional argument is defined in `argparse` without `nargs='?'` or a `default` value, it becomes a required argument. If such an argument is omitted from the command line, `argparse` will raise an error indicating that the argument is required and then exit. ↓

fix Ensure all required positional arguments are provided on the command line. If an argument should be optional, define it with `nargs='?'` or provide a `default` value.

Install

# argparse is included in the Python standard library since 2.7 and 3.2.
# No installation is typically required for modern Python versions.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.00s 17.9M

3.10 alpine (musl) - - 0.00s 17.9M

3.10 slim (glibc) wheel 1.5s 0.00s 18M

3.10 slim (glibc) - - 0.00s 18M

3.11 alpine (musl) wheel - 0.01s 19.8M

3.11 alpine (musl) - - 0.01s 19.8M

3.11 slim (glibc) wheel 1.6s 0.01s 20M

3.11 slim (glibc) - - 0.01s 20M

3.12 alpine (musl) wheel - 0.01s 11.7M

3.12 alpine (musl) - - 0.01s 11.7M

3.12 slim (glibc) wheel 1.5s 0.01s 12M

3.12 slim (glibc) - - 0.01s 12M

3.13 alpine (musl) wheel - 0.01s 11.4M

3.13 alpine (musl) - - 0.01s 11.3M

3.13 slim (glibc) wheel 1.5s 0.00s 12M

3.13 slim (glibc) - - 0.00s 12M

3.9 alpine (musl) wheel - 0.00s 17.4M

3.9 alpine (musl) - - 0.00s 17.4M

3.9 slim (glibc) wheel 1.8s 0.00s 18M

3.9 slim (glibc) - - 0.00s 18M

Imports

argparse
```
import argparse
```

Quickstart last tested: 2026-04-24

This quickstart defines a basic command-line tool that takes a required 'name' argument and an optional '--verbose' flag. It demonstrates creating an `ArgumentParser`, adding arguments, and parsing them.

import argparse

def main():
    parser = argparse.ArgumentParser(
        description='A simple command-line tool.'
    )
    parser.add_argument(
        'name', 
        type=str, 
        help='The name to greet.'
    )
    parser.add_argument(
        '-v', '--verbose', 
        action='store_true', 
        help='Enable verbose output.'
    )

    args = parser.parse_args()

    if args.verbose:
        print(f"Verbose mode enabled. Greeting {args.name}...")
    print(f"Hello, {args.name}!")

if __name__ == '__main__':
    main()