How to Handle Command Line Arguments in Python

Not every application has to have a GUI; many powerful applications are purely command-line-based. In order to build powerful applications, one must harness the power of Python command line arguments. 

Handling command line arguments in your application will make it more flexible. Instead of hard-coding values into your script, you can parse the arguments sent to the application to dynamically change how the code executes.

Using sys.argv to handle Python command line arguments

The first method of parsing command line arguments in Python we will be exploring uses of the sys module. The sys module provides functions and variables that can manipulate parts of the Python runtime environment. It stores the command line arguments to a script in the variable argv as a list of strings.

Here is a straightforward example. This is our python script that is stored as main.py:

import sys

print ("The name of this script is %s" % (sys.argv[0]))

And we would run this Python script with the following command:

python main.py

which will print out:

The name of this script is main.py

The command line arguments to this script are stored as a list of strings. We can access the first argument with an index of 0, which is the file name of the script itself.

Counting the arguments

As we see above, the first argument in the argv list is the name of the script, so to count the number of arguments that the script will actually use, we must ignore the first argument:

import sys

args = len(sys.argv) - 1
print ("The script was called with %i arguments" % (args))

When we run this script with a list of command line arguments, here is the result:

python main.py arg1 arg2 arg3 # Prints "The script was called with 3 arguments"

One thing to note is that the sys module considers the parameters to be delimited by spaces unless you use double quotes around the parameter. So if your parameter has spaces, make sure to put quotes around them:

python main.py arg1 arg2 "arg with spaces" # Prints "The script was called with 3 arguments"

Looping through the arguments

Counting the arguments is a good way to check that your script is getting all the arguments required, but when you want to use the arguments, you can do it this way:

import sys

args = len(sys.argv) - 1

pos = 1
while (args >= pos):
    print ("Parameter at position %i is %s" % (pos, sys.argv[pos]))
    pos = pos + 1

We can run this Python program with some parameters and see what happens:

python main.py --help value=2 X Y

This prints the following:

Parameter at position 1 is --help
Parameter at position 2 is value=2
Parameter at position 3 is X
Parameter at position 4 is Y

Using getopt to handle Python command line arguments

As you see in the last example, sys.argv could be helpful for position-based arguments. In other words, if you always pass the arguments in the same order, it will work fine. But what if you wanted keyword-based arguments? While you could write some code to make this work, the Python getopt module makes it easier.

The Python getopt module works with sys.argv to parse the command line and extract the arguments into a list of tuples when you are using keyword-based arguments. Here is how to use getopt in a Python script that is passed arguments. The comments in the code will explain what is happening:

import getopt
import sys

# Create a list of arguments without the name of the script
argv = sys.argv[1:]
# Set the short options we are expecting (i.e -h or -v)
short_opts = "hv:"
# Set the long options we are expecting (i.e --help or value=)
long_opts = ["help", "value="]

# Pass the argument list to getopt along with the options we are expecting
try:
	args, opts = getopt.getopt(argv, short_opts, long_opts)
except getopt.error as err:
	print (str(err))
  
## Loop through arguments
for current_argument, current_value in args:
    if current_argument in ("-h", "--help"):
        print ("Show this help message")
    elif current_argument in ("-v", "--value"):
        print (("Show the value: %s") % (current_value))

We can run this script with command line options in either of these two ways:

python main.py -h
# Or
python main.py --help

The script will print “Show this help message”.

The other argument we are parsing has a value. We tell getopt this by adding “=” to the long option and “:” to the short options. So we can run it in either of these ways:

python main.py --value=42
# Or
python main.py -v=2

The script will print “Show the value: 2”.

Using argparse to handle Python command line arguments

The argparse module has been available since Python 3.2 and adds some features to the optparse module. Unlike the other two methods above where we had to write extra code, this Python module adds a standardized output to the command line interface that takes care of a lot of the work for you. It also adds verification of optional and fixed arguments, help messages, and automated error handling when an argument is used incorrectly.

Here is an example of Python code you could use:

import argparse

# Instantiate the parser and give it a description that will show before help
parser = argparse.ArgumentParser(description='My Parser')

# Add arguments to the parser
parser.add_argument('--firstname', dest='firstname', type=str, help='Your first name')
parser.add_argument('--lastname', dest='lastname', type=str, help='Your last name')
parser.add_argument('--age', dest='age', type=int, help='Your age')

# Run method to parse the arguments
args = parser.parse_args()

# Print the result
print (("Your name is %s %s and you are %i") % (args.firstname, args.lastname, args.age))

We can run the script above with the following arguments:

python main.py --firstname Bob --lastname Smith --age 25

The script will print “Your name is Bob Smith and you are 25”.

An important part of the script is the add_argument method. The first argument we pass to this method is the name of the parameter we are looking for (i.e., firstname). The dest argument tells argparse the name of the attribute that will be added to the object returned by the parse_args method (i.e., firstname). The type parameter tells argparse the data type we expect this command line argument to be (i.e., str). And the help argument is a description of what the argument is (i.e., Your first name). You can see the help message by running the following:

python main.py -h # Or python main.py --help

This will print out the following:

usage: main.py
       [-h]
       [--firstname FIRSTNAME]
       [--lastname LASTNAME]
       [--age AGE]

My Parser

optional arguments:
  -h, --help
    show this
    help
    message and
    exit
  --firstname FIRSTNAME
    Your first
    name
  --lastname LASTNAME
    Your last
    name
  --age AGE
    Your age

All three of these methods will work for parsing arguments, but each works slightly differently. If you want complete control over arguments and how your script handles them, sys.argv is the way to go. If you want the type of help and features you are used to using in other scripts without writing much code, go with argparse. And if you are using a version of Python that is older than 2.7, use getopt.

To learn more about Python, visit What is Python. And to get started learning Python in-depth, visit our extensive list of Python courses that will take your programming skill to the next level.