Text of docs.python.org › 3.13 › library › argparse.html as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

argparse — Parser for command-line options, arguments and subcommands — Python 3.13.18 documentation

Navigation index modules | next | previous | Python » 3.13.18 Documentation » The Python standard library » Command-line interface libraries » argparse — Parser for command-line options, arguments and subcommands | Theme | argparse — Parser for command-line options, arguments and subcommands ¶ Added in version 3.2. Source code: Lib/argparse.py Note While argparse is the default recommended standard library module for implementing basic command line applications, authors with more exacting requirements for exactly how their command line applications behave may find it doesn’t provide the necessary level of control.

Refer to Choosing an argument parsing library for alternatives to consider when argparse doesn’t support behaviors that the application requires (such as entirely disabling support for interspersed options and positional arguments, or accepting option parameter values that start with - even when they correspond to another defined option). The argparse module makes it easy to write user-friendly command-line interfaces.

The program defines what arguments it requires, and argparse will figure out how to parse those out of sys.argv . The argparse module also automatically generates help and usage messages. The module will also issue errors when users give the program invalid arguments. The argparse module’s support for command-line interfaces is built around an instance of argparse.ArgumentParser . It is a container for argument specifications and has options that apply to the parser as whole: parser = argparse .

ArgumentParser ( prog = 'ProgramName' , description = 'What the program does' , epilog = 'Text at the bottom of help' ) The ArgumentParser.add_argument() method attaches individual argument specifications to the parser. It supports positional arguments, options that accept values, and on/off flags: parser . add_argument ( 'filename' ) # positional argument parser . add_argument ( '-c' , '--count' ) # option that takes a value parser . add_argument ( '-v' , '--verbose' , action = 'store_true' ) # on/off flag The ArgumentParser.parse_args() method runs the parser and places the extracted data in a argparse.Namespace object: args = parser . parse_args () print ( args . filename , args . count , args . verbose ) Note If you’re looking for a guide about how to upgrade optparse code to argparse , see Upgrading Optparse Code .

ArgumentParser objects ¶ class argparse. ArgumentParser ( prog = None , usage = None , description = None , epilog = None , parents = [] , formatter_class = argparse.HelpFormatter , prefix_chars = '-' , fromfile_prefix_chars = None , argument_default = None , conflict_handler = 'error' , add_help = True , allow_abbrev = True , exit_on_error = True ) ¶ Create a new ArgumentParser object. All parameters should be passed as keyword arguments.

Each parameter has its own more detailed description below, but in short they are: prog - The name of the program (default: os.path.basename(sys.argv[0]) ) usage - The string describing the program usage (default: generated from arguments added to parser) description - Text to display before the argument help (by default, no text) epilog - Text to display after the argument help (by default, no text) parents - A list of ArgumentParser objects whose arguments should also be included formatter_class - A class for customizing the help output prefix_chars - The set of characters that prefix optional arguments (default: ‘-‘) fromfile_prefix_chars - The set of characters that prefix files from which additional arguments should be read (default: None ) argument_default - The global default value for arguments (default: None ) conflict_handler - The strategy for resolving conflicting optionals (usually unnecessary) add_help - Add a -h/--help option to the parser (default: True ) allow_abbrev - Allows long options to be abbreviated if the abbreviation is unambiguous. (default: True ) exit_on_error - Determines whether or not ArgumentParser exits with error info when an error occurs. (default: True ) Changed in version 3.5: allow_abbrev parameter was added.

Changed in version 3.8: In previous versions, allow_abbrev also disabled grouping of short flags such as -vv to mean -v -v . Changed in version 3.9: exit_on_error parameter was added. The following sections describe how each of these are used. prog ¶ By default, ArgumentParser calculates the name of the program to display in help messages depending on the way the Python interpreter was run: The base name of sys.argv[0] if a file was passed as argument.

The Python interpreter name followed by sys.argv[0] if a directory or a zipfile was passed as argument. The Python interpreter name followed by -m followed by the module or package name if the -m option was used. This default is almost always desirable because it will make the help messages match the string that was used to invoke the program on the command line. However, to change this default behavior, another value can be supplied using the prog= argument to ArgumentParser : >>> parser = argparse .

ArgumentParser ( prog = 'myprogram' ) >>> parser . print_help () usage: myprogram [-h] options: -h, --help show this help message and exit Note that the program name, whether determined from sys.argv[0] or from the prog= argument, is available to help messages using the %(prog)s format specifier. >>> parser = argparse . ArgumentParser ( prog = 'myprogram' ) >>> parser . add_argument ( '--foo' , help = 'foo of the %(prog)s program' ) >>> parser . print_help () usage: myprogram [-h] [--foo FOO] options: -h, --help show this help message and exit --foo FOO foo of the myprogram program usage ¶ By default, ArgumentParser calculates the usage message from the arguments it contains.

The default message can be overridden with the usage= keyword argument: >>> parser = argparse . ArgumentParser ( prog = 'PROG' , usage = ' %(prog)s [options]' ) >>> parser . add_argument ( '--foo' , nargs = '?' , help = 'foo help' ) >>> parser . add_argument ( 'bar' , nargs = '+' , help = 'bar help' ) >>> parser . print_help () usage: PROG [options] positional arguments: bar bar help options: -h, --help show this help message and exit --foo [FOO] foo help The %(prog)s format specifier is available to fill in the program name in your usage messages. description ¶ Most calls to the ArgumentParser constructor will use the description= keyword argument.

This argument gives a brief description of what the program does and how it works. In help messages, the description is displayed between the command-line usage string and the help messages for the various arguments. By default, the description will be line-wrapped so that it fits within the given space. To change this behavior, see the formatter_class argument. epilog ¶ Some programs like to display additional description of the program after the description of the arguments.

Such text can be specified using the epilog= argument to ArgumentParser : >>> parser = argparse . ArgumentParser ( ... description = 'A foo that bars' , ... epilog = "And that's how you'd foo a bar" ) >>> parser . print_help () usage: argparse.py [-h] A foo that bars options: -h, --help show this help message and exit And that's how you'd foo a bar As with the description argument, the epilog= text is by default line-wrapped, but this behavior can be adjusted with the formatter_class argument to ArgumentParser . parents ¶ Sometimes, several parsers share a common set of arguments.

Rather than repeating the definitions of these arguments, a single parser with all the shared arguments and passed to parents= argument to ArgumentParser can be used. The parents= argument takes a list of ArgumentParser objects, collects all the positional and optional actions from them, and adds these actions to the ArgumentParser object being constructed: >>> parent_parser = argparse . ArgumentParser ( add_help = False ) >>> parent_parser . add_argument ( '--parent' , type = int ) >>> foo_parser =

The rest of this page is on the live site.