Title: Python argparse, and command line arguments - PyImageSearch

URL Source: https://pyimagesearch.com/2018/03/12/python-argparse-command-line-arguments/

Published Time: 2018-03-12T14:00:41+00:00

Markdown Content:
[![Image 1: using python argparse in the command line](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20239'%3E%3C/svg%3E)](https://pyimagesearch.com/wp-content/uploads/2018/03/command_line_arguments_example01.gif)

Today we are going to discuss a fundamental developer, engineer, and computer scientist skill — **command line arguments using Python argparse.**

Specifically, we’ll be discussing:

*   What are command line arguments
*   Why we use command line arguments
*   How to parse command line arguments with Python

Command line arguments are an elementary skill that you must learn how to use, especially if you are trying to apply more advanced computer vision, image processing, or deep learning concepts.

While not directly requiring a dataset, using Python argparse in the context of data-driven tasks, such as processing a dataset of images, can help you understand its usefulness in providing flexible command-line options to your Python scripts.

[Roboflow](https://roboflow.com/?ref=pyimagesearch) has free tools for each stage of the computer vision pipeline that will streamline your workflows and supercharge your productivity.

Sign up or Log in to your [Roboflow account](https://roboflow.com/?ref=pyimagesearch) to access state of the art dataset libaries and revolutionize your computer vision pipeline.

You can start by choosing your own datasets or using our [PyimageSearch’s assorted library of useful datasets](https://universe.roboflow.com/pyimagesearch?ref=pyimagesearch).

Bring data in any of 40+ formats to [Roboflow](https://roboflow.com/?ref=pyimagesearch), train using any state-of-the-art model architectures, deploy across multiple platforms (API, NVIDIA, browser, iOS, etc), and connect to applications or 3rd party tools.

If you are new to command line arguments or do not know how to use them _that’s okay!_ **But you still need to take the time to educate yourself on how to use them** — this post will help you do exactly that.

By the end of today’s post you will have a strong understanding of command line arguments, how they work, and how to use them.

![Image 2](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20128%20128'%3E%3C/svg%3E)

#### Looking for the source code to this post?

[Jump Right To The Downloads Section](#download-the-code)

Each day I receive 3-5 emails or comments from PyImageSearch readers who are struggling with command line arguments.

In fact, just an hour before I decided to write this blog post, I received the following email from Arjun:

> Hey Adrian, I just downloaded the source code to your [deep learning face detection blog post](https://pyimagesearch.com/2018/02/26/face-detection-with-opencv-and-deep-learning/), but when I execute it I get the following error:
> 
> $ python detect\_faces.py  
> usage: detect\_faces.py \[-h\] -i IMAGE -p PROTOTXT -m MODEL \[-c CONFIDENCE\]  
> detect\_faces.py: error: the following arguments are required: -i/–image, -p/–prototxt, -m/–model
> 
> Help!

Arjun is far from alone in struggling with this error.

Many other readers run into similar problems when working with command line arguments — **but the honest truth is that nearly _all_ of these errors can be avoided by taking the time to educate yourself on command line arguments.**

Inside the rest of today’s post you’ll learn that command line arguments are _a lot_ easier to work with than they seem (even if you have never used them before).

You’ll find that you do not have to modify a single line of code to work with them. And by the end of the post you’ll be able to work with command line arguments like a pro.

Let’s get started.

### What are command line arguments?

Command line arguments are flags given to a program/script at runtime. They contain additional information for our program so that it can execute.

Not all programs have command line arguments as not all programs need them. That being said, on this blog we make extensive use of command line arguments in our Python scripts and I’d even go so far to say that 98% of the articles on this blog make use of them.

### Why do we use command line arguments?

As stated, command line arguments give additional information to a program at runtime.

**This allows us to give our program different input on the fly _without changing the code_.**

You can draw the analogy that a command line argument is similar to a function parameter. If you know how functions are declared and called in various programming languages, then you’ll immediately feel at home when you discover how to use command line arguments.

Given that this is computer vision and image processing blog, a lot of the arguments you’ll see here are image paths or video paths.

In the case of deep learning, for which this blog is also known, you’ll see model paths or epoch counts as command line arguments.

In the remainder of today’s post we will learn about the Python argparse package via two script examples.

I’ll also be showing how PyCharm users can run a script without ever leaving PyCharm if they so choose.

### The Python argparse library

[![Image 3: Terminal using Python argparse to run script with command line arguments.](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20239'%3E%3C/svg%3E)](https://pyimagesearch.com/wp-content/uploads/2018/03/command_line_arguments_example01.gif)

**Figure 1:** My terminal screen is used to run a Python script with command line arguments.

First, let’s make a new script, naming it `simple_example.py` :

\# import the necessary packages
import argparse

# construct the argument parse and parse the arguments
ap = argparse.ArgumentParser()
ap.add\_argument("-n", "--name", required=True,
	help="name of the user")
args = vars(ap.parse\_args())

# display a friendly message to the user
print("Hi there {}, it's nice to meet you!".format(args\["name"\]))

First, we need the Python `argparse` package, so we go ahead and import it on **Line 2.**

On **Line 5** we instantiate the `ArgumentParser` object as `ap` .

Then on **Lines 6 and 7** we add our only argument, `--name` . We must specify both _shorthand_ (`-n`) and _longhand_ versions (`--name`) where either flag could be used in the command line. This is a required argument as is noted by `required=True` .

The `help` string from **Line 7** will give additional information in the terminal if you need it. To view the command usage help you may enter the following in the terminal (output directly below):

$ python simple\_example.py --help
usage: simple\_example.py \[-h\] -n NAME

optional arguments:
  -h, --help            show this help message and exit
  -n NAME, --name NAME  name of the user

Notice how I specified all three of:

1.  The executable (`python` )
2.  Our Python script file (`simple_example.py` )
3.  And an argument (`--help` ) in order to print the usage.

**Line 8** of the script instructs Python and the `argparse` library to parse the command line arguments. I also call `vars` on the object to turn the parsed command line arguments into a Python dictionary where the _key_ to the dictionary is the name of the command line argument and the value is _value_ of the dictionary supplied for the command line argument. To see this in action I would suggest inserting a `print(args)` statement into the code.

While optional, I prefer converting the arguments object to a dictionary so I can execute the script via my command line or in a Jupyter Notebook. When using a Jupyter Notebook I can simply delete the command line arguments parsing code and insert a dictionary named `args` with any hardcoded values.

Now you’re probably wondering: **How can I access the value from the command line argument argument?**

That’s simple, and there’s an example on **Line 11** of the script.

In the format string, we specify `args["name"]` . As you’ll see shortly, we’ll print our name to the screen dynamically with this command line argument.

Here are the steps we need to take in order to execute our `simple_example.py` script:

1.  **Step 1:** Download the zip accompanying this blog post from the _**“Downloads”**_ section into a location on your machine of your choosing (I would suggest the Desktop for sake of simplicity).
2.  **Step 2:** Open a terminal and change directory to where the zip lives.
3.  **Step 3:** Unzip.
4.  **Step 4:** Change directory again, this time into the new directory that was just extracted.
5.  **Step 5:** Activate your virtual environment with the `workon` command. Example: `workon cv` or `workon py3cv4` (depending on the name of your environment). If you are using my [Pre-configured Raspbian .img](https://pyimagesearch.com/2016/11/21/raspbian-opencv-pre-configured-and-pre-installed/), it is recommended to use the `source` command with the script in the home folder. Example: `source ~/start_py3cv4.sh` or `source ~/start_openvino.sh` . For OpenVINO it is especially important to use the `source` command as it loads a handful of environment variables in addition to activating your virtual environment.
6.  **Step 6:** Execute the program (with command line arguments) and view the output.

On this blog, I show commands and their arguments in a “shell” codeblock. The `$` at the beginning of the prompt is your queue that this is a terminal command and you should enter the command after the `$` character along with your preferred arguments similar to or exactly as written.

I’ve taken care of **Step 1** by downloading the code to this lesson to my Desktop in my PyImageSearch directory for easy access.

From there, I entered the following commands and generated the accompanying output:

$ cd ~/Desktop/PyImageSearch
$
$ unzip command-line-arguments.zip
...
$
$ cd command-line-arguments
$ pwd
/Users/adrianrosebrock/Desktop
$
$ python simple\_example.py --name Adrian
Hi there Adrian, it's nice to meet you!
$
$ python simple\_example.py --name Stephanie
Hi there Stephanie, it's nice to meet you!
$
$ python simple\_example.py --name YourNameHere
Hi there YourNameHere, it's nice to meet you!

Let’s walk through what I’ve demonstrated in the terminal above while referring to **Steps 2-5**.

**Step 2:**

I _changed directory_ to where I downloaded the zip for this lesson (**Line 1**).

I pressed the enter/return button on **Line 2** to make the output easier to read. This is optional.

**Step 3:**

I _unzipped the .zip file_ associated with this lesson (**Line 3**).

The `...` on **Line 4** signifies that there was output from the unzipping process but I am not showing it here. Note that output doesn’t have a preceding `$` .

**Step 4:**

Next I need to _change directory_ into the folder that I just unzipped (**Line 6**).

Just to be sure I’m where I need to be, I _print my working directory_ on **Line 7** with the output being shown on **Line 8**.

**Step 5:**

I _execute the command with argument_ on **Line 10**. I’m specifying my name after the `--name` flag. As long as my name doesn’t have any spaces, it will be displayed properly in the output.

The output is displayed on **Line 11.** Notice how the script _dynamically_ shows my name exactly as I entered it in the command. Command line arguments are powerful and allow you to test your program with different input without changing a line of code.

**Lines 13-17** demonstrate two additional examples that my script with no code changes will print a given name. Try it yourself with your own name…or maybe that of your nemesis.

_**Note:** If I execute **Step 5** without command line arguments (or with incorrect ones), I’ll see usage/error information printed as is shown._

$ python simple\_example.py
usage: simple\_example.py \[-h\] -n NAME
simple\_example.py: error: argument -n/--name is required

This simple example helped us to grasp the concept of command line arguments; however it is not very useful to print a sentence containing our name.

In the next section I’ll provide a more practical example of using command line arguments

### Parsing command line arguments with Python

[![Image 4](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20239'%3E%3C/svg%3E)](https://pyimagesearch.com/wp-content/uploads/2018/03/command_line_arguments_example02.gif)

**Figure 2:** Using the Python argparse package you can easily parse command line arguments in the terminal/command line.

In this next example we’ll be counting shapes in any given input image while annotating an output image that gets written to disk.

We’ll be making use of command line arguments again to specify the input image path and the output image path.

The image processing technicals will be light for this explanation — after all we’re just making this example for the purposes of command line arguments.

So let’s create a new file called `shape_counter.py` and start coding:

Codeblock #1: Lines 1-20# import the necessary packages
import argparse
import imutils
import cv2

# construct the argument parser and parse the arguments
ap = argparse.ArgumentParser()
ap.add\_argument("-i", "--input", required=True,
	help="path to input image")
ap.add\_argument("-o", "--output", required=True,
	help="path to output image")
args = vars(ap.parse\_args())

# load the input image from disk
image = cv2.imread(args\["input"\])

# convert the image to grayscale, blur it, and threshold it
gray = cv2.cvtColor(image, cv2.COLOR\_BGR2GRAY)
blurred = cv2.GaussianBlur(gray, (5,5), 0)
thresh = cv2.threshold(blurred, 60, 255, cv2.THRESH\_BINARY)\[1\]

We import `argparse` on **Line 2** — this is the package that will help us parse and access our command line arguments.

Then, on **Lines 7-12** we parse two command line arguments. The code is very readable on these lines and you can see how to format an argument.

Let’s take the `--input` argument as an example.

On **Line 7** we instantiate the `ArgumentParser` object as `ap` .

Then on **Lines 8 and 9** we add our `--input` argument. We must specify shorthand and longhand versions (`-i` and `--input` ) where either flag could be used in the command line. This is a required argument as is noted by `required=True` . The `help` string will give additional information in the terminal as I demonstrated above.

Similarly, on **Lines 10 and 11**, we specify our `--output` argument which is also required.

From there we load the image using the path. Remember, the input image path is contained in `args["input"]` , so that is the parameter to `cv2.imread` .

Simple, right?

The rest of the lines are image processing specific, so if you’ve landed on this blog without any OpenCV or image processing skills, you might want to poke around in the archives for further explanations on these concepts.

On **Lines 18-20** we complete three operations:

1.  Convert the `image` to grayscale.
2.  Blur the grayscale image.
3.  Threshold the `blurred` image.

We’re ready to find and draw shape contours:

\# extract contours from the image
cnts = cv2.findContours(thresh.copy(), cv2.RETR\_EXTERNAL,
	cv2.CHAIN\_APPROX\_SIMPLE)
cnts = imutils.grab\_contours(cnts)

# loop over the contours and draw them on the input image
for c in cnts:
	cv2.drawContours(image, \[c\], -1, (0, 0, 255), 2)

# display the total number of shapes on the image
text = "I found {} total shapes".format(len(cnts))
cv2.putText(image, text, (10, 20), cv2.FONT\_HERSHEY\_SIMPLEX, 0.5,
		(0, 0, 255), 2)

# write the output image to disk
cv2.imwrite(args\["output"\], image)

On **Lines 23-25** we’re finding shape contours in the `thresh` image.

From there, we draw the contours on the input image (**Lines 28 and 29**).

To learn more about contours, please see _[Finding Shapes in Images using Python and OpenCV](https://pyimagesearch.com/2014/10/20/finding-shapes-images-using-python-opencv/)_ and the [contours tag archives](https://pyimagesearch.com/tag/contours/). I also discuss contours and other image processing fundamentals in my book, _[Practical Python and OpenCV + Case Studies](https://pyimagesearch.com/practical-python-opencv/)_.

Then we assemble and put text on the image (**Lines 32-34**). The text contains the total number of shapes.

Lastly, we make use of our `--output` image path argument to write the image to disk with `cv2.imwrite` (**Line 37**).

Let’s execute the command with our two arguments:

$ python shape\_counter.py --input input\_01.png --output output\_01.png

If you inspect your working directory, you’ll notice the `output_01.png` image is now present:

[![Image 5](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20600%20561'%3E%3C/svg%3E)](https://pyimagesearch.com/wp-content/uploads/2018/03/output_01.png)

**Figure 3:** Shapes have been counted with our Python + OpenCV script which takes in command line arguments.

Let’s execute the command again with different arguments:

$ python shape\_counter.py --input input\_02.png --output output\_02.png

Again, you’ll notice a new output file in your directory: `output_02.png` .

[![Image 6](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20400%20300'%3E%3C/svg%3E)](https://pyimagesearch.com/wp-content/uploads/2018/03/command_line_arguments_output02.png)

**Figure 4:** Three shapes have been detected with OpenCV and Python by simply changing the command line arguments.

Now, take a step back. and consider what we have done from a command line arguments perspective.

What we did here is use _one script_ with _no changes_ and provided it _different arguments_. The `--input` argument contained the path/filename of the input image and likewise with `--output` .

The concept is extremely simple and I hope this has cleared up how to use command line arguments. Before we wrap up this post, let’s take a look at what _not_ to do.

### How to _not_ parse command line arguments

Every now and then I see readers who attempt to modify the code itself to accept command line arguments.

A great example of how not to parse command line arguments can be seen by starting with our command line arguments on **Lines 6-12** from the previous section:

\# construct the argument parser and parse the arguments
ap = argparse.ArgumentParser()
ap.add\_argument("-i", "--input", required=True,
	help="path to input image")
ap.add\_argument("-o", "--output", required=True,
	help="path to output image")
args = vars(ap.parse\_args())

I’ve seen readers mistakenly try to update the argument parsing code to include the actual path to the input image:

\# construct the argument parser and parse the arguments
ap = argparse.ArgumentParser()
ap.add\_argument("-i", "C:\\example\\input\_image.png", required=True,
	help="path to input image")
ap.add\_argument("-o", "C:\\example\\output\_image.png", required=True,
	help="path to output image")
args = vars(ap.parse\_args())

Or in a list ditch effort, try to use the `help` parameter to include the file path:

\# construct the argument parser and parse the arguments
ap = argparse.ArgumentParser()
ap.add\_argument("-i", "--input", required=True,
	help="/home/pi/my\_input.png")
ap.add\_argument("-o", "--output", required=True,
	help="/home/pi/output\_image.png")
args = vars(ap.parse\_args())

Keep in mind that _**the code itself does not need to be updated.**_

Take a second to open up your terminal, navigate to where your code lives, and then execute the script, making sure to provide the command line arguments.

I want to share another “gotcha” with you. Sometimes on this blog, my command line argument flags have a ‘-‘ (dash) in them such as `--features-db` . It’s a little bit confusing and a bit of a nuissance that when grabbing the value contained by the argument, you need to use a ‘\_’ (underscore).

This is demonstrated in this excerpt from the [PyImageSearch Gurus course](https://pyimagesearch.com/pyimagesearch-gurus/) Content Based Image Retrieval Module:

\# construct the argument parser and parse the arguments
ap = argparse.ArgumentParser()
ap.add\_argument("-d", "--dataset", required=True, help="Path to the directory of indexed images")
ap.add\_argument("-f", "--features-db", required=True, help="Path to the features database")
ap.add\_argument("-c", "--codebook", required=True, help="Path to the codebook")
ap.add\_argument("-o", "--output", required=True, help="Path to output directory")
args = vars(ap.parse\_args())

# load the codebook and open the features database
vocab = pickle.loads(open(args\["codebook"\], "rb").read())
featuresDB = h5py.File(args\["features\_db"\], mode="r")
print("\[INFO\] starting distance computations...")

Notice on the highlighted lines that I’ve defined the argument as `--features-db` (with a dash), but I reference it by `args["features_db"]` (with an underscore). This is because the Python `argparse` library replaces dashes with underscores during the parsing.

### You can do it!

Command line arguments may take some practice or getting used to if you are new to working in a terminal — **but I have faith in you!**

Don’t get discouraged.

Take your time.

And keep practicing.

Before you know it, you’ll have mastered command line arguments — **take the time now to invest in your education and this valuable skill!**

### Setting your command line arguments via an IDE

From time to time I receive emails and blog comments asking how to run Python scripts from within their IDE.

About 90% of the time the question is similar to:

> Hi Adrian,
> 
> Help! I can’t get the code to run.
> 
> How can I run the code from your blog post with PyCharm?

PyCharm and other IDEs are great tools that are packed with features. I love PyCharm and I use it daily.

While it’s possible to run a script with command line arguments in an IDE, _I do not advise it_.

You really need to get comfortable with the command line when you’re doing development. It actually saves time to use the terminal rather than to click around the GUI of your IDE and set up the arguments.

In an effort to serve the community, I’m providing two screencasts that were captured by David Hoffman — you’ll hear my familiar voice as I recorded the voiceover to explain the steps.

**Step 1** is to grab the code to this tutorial (or another one on this blog if you are so inclined) via the _**“Downloads”**_ section.

As you’ll see in the video, David downloaded the code into a folder residing on his desktop. Once you’ve put the download somewhere convenient for you, press play and follow along:

David and I took it a step further to demonstrate that you can select a virtual environment for your PyCharm run configuration.

The second example in this blog post requires that you have OpenCV installed.

Since David was a student of the [PyImageSearch Gurus course](https://pyimagesearch.com/pyimagesearch-gurus/), he used his `gurus` virtual environment. You can select an environment on your own system that you’ve set up with OpenCV. If you don’t have such an environment, you should follow [my OpenCV installation instructions](https://pyimagesearch.com/opencv-tutorials-resources-guides/).

To watch the more advanced PyCharm + Run Configuration which uses command line arguments, click play below.

As you can see, both examples are relatively easy. PyCharm provides a convenient way to test code without using your terminal. I’m still partial to using the terminal as I’ve always got it open anyway for the many tasks that PyCharm can’t handle.

#### Did your virtual environment not show up in PyCharm?

Don’t worry!

You might just need to browse to the `~/.virtualenvs` folder and select your interpreter (all from within the PyCharm Run Configuration screen).

### What's next? We recommend [PyImageSearch University](https://pyimagesearch.com/pyimagesearch-university/?utm_source=blogPost&utm_medium=bottomBanner&utm_campaign=What%27s%20next%3F%20I%20recommend).

**Course information:**  
84 total classes • 114+ hours of on-demand code walkthrough videos • Last updated: February 2024  
★★★★★ 4.84 (128 Ratings) • 16,000+ Students Enrolled

**I strongly believe that if you had the right teacher you could _master_ computer vision and deep learning.**

Do you think learning computer vision and deep learning has to be time-consuming, overwhelming, and complicated? Or has to involve complex mathematics and equations? Or requires a degree in computer science?

That’s _not_ the case.

All you need to master computer vision and deep learning is for someone to explain things to you in _simple, intuitive_ terms. _And that’s exactly what I do_. My mission is to change education and how complex Artificial Intelligence topics are taught.

If you're serious about learning computer vision, your next stop should be PyImageSearch University, the most comprehensive computer vision, deep learning, and OpenCV course online today. Here you’ll learn how to _successfully_ and _confidently_ apply computer vision to your work, research, and projects. Join me in computer vision mastery.

**Inside PyImageSearch University you'll find:**

*   ✓ **84 courses** on essential computer vision, deep learning, and OpenCV topics
*   ✓ **84 Certificates** of Completion
*   ✓ **114+ hours** of on-demand video
*   ✓ **Brand new courses released _regularly_**, ensuring you can keep up with state-of-the-art techniques
*   ✓ **Pre-configured Jupyter Notebooks in Google Colab**
*   ✓ Run all code examples in your web browser — works on Windows, macOS, and Linux (no dev environment configuration required!)
*   ✓ Access to **centralized code repos for _all_ 536+ tutorials** on PyImageSearch
*   ✓ **Easy one-click downloads** for code, datasets, pre-trained models, etc.
*   ✓ **Access** on mobile, laptop, desktop, etc.

[Click here to join PyImageSearch University](https://pyimagesearch.com/pyimagesearch-university/?utm_source=blogPost&utm_medium=bottomBanner&utm_campaign=What%27s%20next%3F%20I%20recommend)

Summary
-------

In today’s blog post you learned how to utilize command line arguments using the Python programming language.

You also learned how to utilize the `argparse` library for parsing command line arguments.

At this point you should now understand the fundamentals of command line arguments and the role they play in software, programs, and scripts.

As you saw, when used correctly, you do not have to modify _any_ code to work with command line arguments — just open up a terminal, navigate to your Python script, and execute it!

Additionally, if you are new to the Python programming language and want to level up your Python coding skills, We have put together an [intro to python course](https://pyimagesearch.com/intro-python-course/) for you — be sure to give it a look.

**If you enjoyed today’s blog post _be sure enter your email address in the form below_ to be notified when future blog posts are published!**

![Image 7](data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20410%20567'%3E%3C/svg%3E)

#### Download the Source Code and FREE 17-page Resource Guide

Enter your email address below to get a .zip of the code and a **FREE 17-page Resource Guide on Computer Vision, OpenCV, and Deep Learning.** Inside you'll find my hand-picked tutorials, books, courses, and libraries to help you master CV and DL!