Introduction

When a Python script needs multiple values from the command line, the cleanest solution is usually to let argparse collect them as a list. The right pattern depends on how the user should type the input: as repeated positional values, repeated options, or one comma-separated string.

Use nargs For Space-Separated Values

The most common approach is to accept several values separated by spaces. argparse does this with nargs.

If the values are positional arguments:

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("numbers", type=int, nargs="+")
5args = parser.parse_args()
6
7print(args.numbers)
8print(sum(args.numbers))

Run it like this:

python app.py 1 2 3 4

The parsed result is a real Python list:

[1, 2, 3, 4]

nargs="+" means one or more values. If you want zero or more, use nargs="*".

Accept Lists On Optional Flags

The same idea works for optional arguments:

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("--names", nargs="+")
5args = parser.parse_args()
6
7print(args.names)

Example:

python app.py --names ava noah mia

This produces:

['ava', 'noah', 'mia']

This style is easy to document and easy for users to type because the shell already understands space-separated tokens.

Use action="append" When The Flag Can Repeat

Sometimes you want users to repeat the same option several times. In that case, append is often clearer than forcing everything into one occurrence.

1import argparse
2
3parser = argparse.ArgumentParser()
4parser.add_argument("--tag", action="append")
5args = parser.parse_args()
6
7print(args.tag)

Example:

python app.py --tag api --tag urgent --tag finance

Result:

['api', 'urgent', 'finance']

This is a good fit when each value is conceptually its own flag occurrence.

Parse A Comma-Separated List Deliberately

If the calling convention requires one argument containing commas, parse that explicitly instead of using type=list, which does not do what most people expect.

1import argparse
2
3def csv_list(value: str) -> list[str]:
4    return [item.strip() for item in value.split(",") if item.strip()]
5
6parser = argparse.ArgumentParser()
7parser.add_argument("--items", type=csv_list)
8args = parser.parse_args()
9
10print(args.items)

Example:

python app.py --items "red, green, blue"

Result:

['red', 'green', 'blue']

This pattern is helpful when values come from shell variables or configuration wrappers that already produce a single string.

Choose The User Experience First

The best answer is not only about what argparse can parse. It is about what your users can type reliably.

Use space-separated values with nargs when:

• users type values manually
• values are simple tokens
• normal shell splitting is desirable

Use repeated flags with append when:

• each value is conceptually a separate option
• you want the command to stay readable
• values may appear conditionally

Use a comma-separated parser when:

• the caller already provides one string
• you are matching an existing CLI contract
• you want to keep the whole list inside one quoted argument

Common Pitfalls

• Using type=list and expecting argparse to split the string automatically.
• Forgetting to quote comma-separated input when the shell would otherwise split or expand it.
• Using nargs="*" when at least one value should be required.
• Mixing repeated flags and nargs without thinking through the resulting nested structure.
• Assuming append and nargs produce the same shape of parsed data.

Summary

• Use nargs for space-separated lists on positional or optional arguments.
• Use action="append" when the same option can appear multiple times.
• For comma-separated input, parse the string yourself with a small helper function.
• Pick the pattern that matches how users will actually type the command.