Python Argument Parser Example (argparse)

argparse helps you build Python programs that accept values from the command line.

This example shows one small, practical script so you can learn the basic idea without learning the whole module at once. You will see how to:

  • accept arguments after the script name
  • convert values to the right type
  • show built-in help
  • use an optional flag

Quick example

Here is a simple script that adds two numbers:

import argparse

parser = argparse.ArgumentParser(description="Add two numbers")
parser.add_argument("x", type=int, help="First number")
parser.add_argument("y", type=int, help="Second number")
args = parser.parse_args()

print(args.x + args.y)

Run it like this:

python app.py 3 5

Output:

8

What this example does

This example is small on purpose.

It shows how to build a real command line program that:

  • uses argparse to read values passed after the script name
  • expects two numbers from the user
  • converts those values to integers
  • prints the result

If you want a fast, working argparse example, this is a good place to start.

When to use argparse

Use argparse when you run a Python script from the terminal and want to pass extra values to it.

It is useful for scripts that need:

  • file names
  • numbers
  • names
  • flags such as --verbose or --uppercase

For beginners, argparse is usually better than reading raw arguments manually because it gives you:

  • automatic help messages
  • type conversion
  • clearer error messages

If you are new to terminal arguments, you may also want to read how to use command line arguments in Python and sys.argv explained later.

Main parts of the example

The script has four main steps.

1. Create an ArgumentParser object

parser = argparse.ArgumentParser(description="Add two numbers")

This creates the parser and sets a short description.

2. Add expected arguments

parser.add_argument("x", type=int, help="First number")
parser.add_argument("y", type=int, help="Second number")

These lines define two positional arguments:

  • x
  • y

They are required, and the user must provide them in the correct order.

3. Parse the command line input

args = parser.parse_args()

This reads the values typed in the terminal.

4. Use the values

print(args.x + args.y)

After parsing, you can access the values with names like args.x and args.y.

Example walkthrough

Here is the full script again:

import argparse

parser = argparse.ArgumentParser(description="Add two numbers")
parser.add_argument("x", type=int, help="First number")
parser.add_argument("y", type=int, help="Second number")
args = parser.parse_args()

print(args.x + args.y)

What each part does:

  • description="Add two numbers" sets the help text shown to the user
  • type=int converts the input from text to integers automatically
  • help="First number" and help="Second number" describe each argument
  • args = parser.parse_args() reads the command line input
  • print(args.x + args.y) uses the parsed values

Without type=int, the arguments would be read as text.

For example, "3" and "5" are strings at first. argparse converts them for you when you use type=int.

Positional arguments vs optional arguments

There are two common kinds of arguments in argparse.

Positional arguments

Positional arguments:

  • are usually required
  • are given by order
  • do not use dashes

Example:

parser.add_argument("name")

Run:

python app.py Alice

Optional arguments

Optional arguments:

  • usually start with - or --
  • are often used for settings or switches
  • do not have to be provided unless you make them required

Example:

parser.add_argument("--uppercase")

Run:

python app.py Alice --uppercase yes

For beginners, the main idea is simple:

  • use positional arguments for required input
  • use optional arguments for extra behavior

Second example with an optional flag

Now let's build a second script that accepts a name and an optional --uppercase flag.

import argparse

parser = argparse.ArgumentParser(description="Greet a user")
parser.add_argument("name", help="The person's name")
parser.add_argument(
    "--uppercase",
    action="store_true",
    help="Show the greeting in uppercase"
)

args = parser.parse_args()

message = f"Hello, {args.name}"

if args.uppercase:
    message = message.upper()

print(message)

How this works

The important new part is:

action="store_true"

This means:

  • if --uppercase is included, args.uppercase becomes True
  • if it is not included, args.uppercase becomes False

Run it without the flag

python app.py Alice

Output:

Hello, Alice

Run it with the flag

python app.py Alice --uppercase

Output:

HELLO, ALICE

This is a common pattern for command line tools.

How to run the script

Save one of the examples in a file named app.py.

Then open a terminal in the same folder.

Example 1: add two numbers

python app.py 3 5

Output:

8

Example 2: wrong type

python app.py hello 5

If your script expects integers, argparse will show an error because hello cannot be converted to int.

Example 3: greeting script

python app.py Alice --uppercase

Output:

HELLO, ALICE

If you are not sure how terminal input differs from normal keyboard input in a script, compare this with how to get user input in Python.

Common beginner mistakes

These are some common problems when learning argparse.

Forgetting required positional arguments

If your script expects x and y, this will fail:

python app.py 3

argparse will show an error because one required argument is missing.

Passing text when the script expects int

If you use type=int, this will fail:

python app.py hello 5

That happens because hello cannot be converted to an integer. A related error you may see in other code is ValueError: invalid literal for int() with base 10.

Misspelling an optional flag

If the flag is --uppercase, then --upper-case or --upper will not work unless you defined them.

Always type the flag name exactly as written in the script.

Trying to use args before calling parse_args()

This is wrong:

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("x", type=int)

print(args.x)  # args does not exist yet
args = parser.parse_args()

You must parse first:

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("x", type=int)

args = parser.parse_args()
print(args.x)

How to read the help output

One of the best things about argparse is that it builds help text automatically.

Run:

python app.py --help

You will see output similar to this:

usage: app.py [-h] x y

Add two numbers

positional arguments:
  x           First number
  y           Second number

options:
  -h, --help  show this help message and exit

This help output includes:

  • the usage line, which shows how to run the script
  • the description, which comes from ArgumentParser(...)
  • the argument help text, which comes from help=...

This is one reason argparse is easier to use than reading raw values from sys.argv.

What to learn next

After this example, a good next step is to learn the bigger picture of command line arguments.

You can continue with:

FAQ

What is argparse in Python?

argparse is a standard library module for reading command line arguments and options.

What is the difference between positional and optional arguments?

Positional arguments are required and depend on order. Optional arguments use flags like --name.

Why use argparse instead of sys.argv?

argparse is easier for beginners because it adds help messages, type conversion, and clearer error messages.

How do I show the help message?

Run the script with --help, such as:

python app.py --help

Can argparse convert input types automatically?

Yes. For example, type=int converts an argument to an integer.

See also