# Command-Line Options with argparse

The words typed after a script's name arrive in sys.argv, and the argparse module turns them into a positional argument, options with defaults and flags, checks them, and writes a --help page, so one script works on any folder without editing its code.

Journeyman · Python · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Read the words typed after a script's name with sys.argv
- Give a script a positional argument, options and a flag with argparse, and read its --help page

## Key takeaways

- The words typed after python script.py arrive in sys.argv, a list of strings whose first item is the script's own name.
- argparse reads those words for you. add_argument("folder") makes a positional argument, one the user must type in its place.
- An option starts with two dashes, such as --days, and gets its default when it's left out. type=int turns the typed text into a number.
- A flag such as --dry-run is True when it's typed and False when it isn't (action="store_true").
- argparse writes the --help page from your help= texts, and stops with a clear message when a required argument is missing or a word is wrong.

The tools you already use in the terminal take instructions on the same line you start them with: `pip install -r requirements.txt` says what to install and where the list is, and `git clone` takes the address to copy. Your own scripts can work the same way. Once a script takes its folder and its settings from the command line, you can run it on any folder, try it safely with a dry run, and hand it to a friend who never opens the code.

The example is a script that tidies a Downloads folder, run on a practice folder named `practice-downloads`.

## A script that only knows one folder

Here's how a tidy-up script usually starts:

```python
FOLDER = "practice-downloads"
DRY_RUN = True

print("Folder:", FOLDER)
print("Dry run:", DRY_RUN)
```

```text
Folder: practice-downloads
Dry run: True
```

It works, for one folder. To tidy another one, or to stop the dry run and make the moves, you open the file and edit it. Anyone else who uses it has to find the right lines first, and an edit made in a hurry is how a script ends up pointed at the wrong folder.

## sys.argv: the words after the script's name

When you start a program in the terminal, Python keeps every word you typed after `python` in a list named `sys.argv` (read "sys dot arg v", short for *argument values*). Each word is a **command-line argument**. Save this as `tidy.py`:

```python
import sys

print(sys.argv)
```

Then run it with two words after its name:

```bash
python tidy.py practice-downloads --dry-run
```

```text
['tidy.py', 'practice-downloads', '--dry-run']
```

The first item is the script's own name, and the rest are the words you typed, always as strings. A script could read `sys.argv[1]` as its folder. Then it would have to check the word is there at all, notice `--dry-run` wherever it comes, turn a number such as `"7"` into `7`, and explain itself when someone types a word wrong. That's a lot of checking, and Python's `argparse` module does all of it for you.

## argparse: say what the script takes

With `argparse`, you describe what the script expects, and it reads `sys.argv` for you:

```python
import argparse

parser = argparse.ArgumentParser(description="Sort a downloads folder into folders by file type.")
parser.add_argument("folder", help="the folder to sort")
parser.add_argument("--to", default="Sorted", help="the folder to sort into (default: Sorted)")
parser.add_argument("--dry-run", action="store_true", help="show what would move, and move nothing")
args = parser.parse_args()

print("Folder:", args.folder)
print("Sort into:", args.to)
print("Dry run:", args.dry_run)
```

Each `add_argument` line adds one thing the script takes:

- `"folder"` has no dashes, so it's a **positional argument**: the user must type it, and its place in the line says what it is.
- `"--to"` starts with two dashes, so it's an **option**: the user may type it with a value after it, and `default="Sorted"` is what it gets when they don't.
- `"--dry-run"` with `action="store_true"` is a **flag**: an option with no value. It's `True` when it's typed and `False` when it isn't.

`parse_args()` reads the words and hands back `args`, with one attribute for each argument. A dash in a name becomes an underscore, because Python names can't hold dashes: `--dry-run` is `args.dry_run`. Two runs:

```bash
python tidy.py practice-downloads --dry-run
python tidy.py practice-downloads --to Tidy
```

```text
Folder: practice-downloads
Sort into: Sorted
Dry run: True
Folder: practice-downloads
Sort into: Tidy
Dry run: False
```

## Numbers, and trying a parser out

Every word typed in the terminal is text. `type=int` tells `argparse` to turn an option's value into a whole number, and to refuse one that isn't. You can also hand `parse_args()` a list of words instead of letting it read the terminal, which is handy for trying a parser out, and for tests:

```python
import argparse

parser = argparse.ArgumentParser()
parser.add_argument("folder")
parser.add_argument("--days", type=int, default=30)

args = parser.parse_args(["practice-downloads", "--days", "7"])
print(args.folder, args.days, args.days + 1)

args = parser.parse_args(["practice-downloads"])
print(args.days)
```

```text
practice-downloads 7 8
30
```

`args.days + 1` is `8`, so `days` is a number, not the text `"7"`. Left out, it gets its default, `30`.

## --help comes free, and so do the error messages

Every `argparse` script answers `--help` (or `-h`) with a page built from your `help=` texts:

```bash
python tidy.py --help
```

```text
usage: tidy.py [-h] [--to TO] [--dry-run] folder

Sort a downloads folder into folders by file type.

positional arguments:
  folder      the folder to sort

options:
  -h, --help  show this help message and exit
  --to TO     the folder to sort into (default: Sorted)
  --dry-run   show what would move, and move nothing
```

The *usage* line reads like a sentence: square brackets mark what you may leave out, and `folder`, outside any brackets, is required. Leave it out, or mistype an option, and the script stops before it touches a file, with a message that says what's wrong:

```bash
python tidy.py
python tidy.py practice-downloads --dryrun
```

```text
usage: tidy.py [-h] [--to TO] [--dry-run] folder
tidy.py: error: the following arguments are required: folder
usage: tidy.py [-h] [--to TO] [--dry-run] folder
tidy.py: error: unrecognized arguments: --dryrun
```

That second stop matters for a script that moves files: a typo in `--dry-run` can't quietly turn into a real run.

## Do it: give the receipt backup its options

A script backs up the receipts in a folder. Its user types the folder, may say how many days back to look, and may ask for a dry run.

**Your job:** finish the function `make_parser()` so the parser it returns takes:

- `folder`: a positional argument, the folder the receipts are in. The starter has it already.
- `--days`: an option holding a whole number (an `int`), `30` when it's left out.
- `--dry-run`: a flag, `True` when it's typed and `False` when it isn't.

Leaving out the folder is an error: `parse_args` stops with `SystemExit`, as the starter's parser already does.

Worked through: `make_parser().parse_args(["practice-downloads", "--days", "7"])` gives `folder` `"practice-downloads"`, `days` the number `7` and `dry_run` `False`, because `--dry-run` wasn't typed.

Practiced live on the lesson page: write the Python right there and check it.

## Check yourself

2 questions to try on the lesson page.

## So what

A script that takes its folder and settings from the command line, with a dry run and a `--help` page, is a tool: you run it on any folder, and so can someone who has never read its code.

## Key terms

- [sys.argv](https://www.ask-codey.com/glossary/sys-argv)
- [argparse](https://www.ask-codey.com/glossary/argparse)
- [Command-Line Argument](https://www.ask-codey.com/glossary/command-line-argument-python)
- [Flags and Options](https://www.ask-codey.com/glossary/flags-and-options)

## Related

- [Paths and Folders with pathlib](https://www.ask-codey.com/lessons/python-automation-paths-with-pathlib)
- [Copying, Moving and Renaming Files Safely](https://www.ask-codey.com/lessons/python-automation-copy-move-rename)
- [Running a Script on a Schedule](https://www.ask-codey.com/lessons/python-automation-scheduled-jobs)

Source: https://www.ask-codey.com/lessons/python-automation-command-line-arguments
