ArgumentParser incorrectly parses dashed option args containing spaces as positional args

[qris]

Bug report

Bug description:

Python 3.13.11 (main, Dec  6 2025, 08:52:52) [GCC 13.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from argparse import ArgumentParser
>>> parser = ArgumentParser(exit_on_error=False)

>>> parser.add_argument('tags', nargs='*')
_StoreAction(option_strings=[], dest='tags', nargs='*', const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None, deprecated=False)
>>> parser.parse_args(['--timeout'])
Traceback (most recent call last):
  File "<python-input-3>", line 1, in <module>
    parser.parse_args(['--timeout'])
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
  File "/usr/lib/python3.13/argparse.py", line 1904, in parse_args
    raise ArgumentError(None, msg)
argparse.ArgumentError: unrecognized arguments: --timeout

>>> parser.parse_args(['--timeout', '1'])
Traceback (most recent call last):
  File "<python-input-4>", line 1, in <module>
    parser.parse_args(['--timeout', '1'])
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.13/argparse.py", line 1904, in parse_args
    raise ArgumentError(None, msg)
argparse.ArgumentError: unrecognized arguments: --timeout

>>> parser.parse_args(['--timeout 1'])
Namespace(tags=['--timeout 1'])

Note that in the last case, there was no complaint about --timeout or --timeout 1 being an unrecognized argument. It was simply silently treated as a positional argument, which seems wrong to me as it starts with two dashes.

Admittedly this is an edge case, but it's easy to hit by mistake when calling such a process with subprocess and a list of arguments, and not necessarily easy to debug.

CPython versions tested on:

3.13

Operating systems tested on:

Linux

[a12k]

Looking at the logic in argparse.py for determining whether an argument string is positional or optional (_parse_optional returns None if it's meant to be positional), I see where it's flagging argument strings containing a space as positional here:

# if it contains a space, it was meant to be a positional
if ' ' in arg_string:
    return None

So this behavior is intentionally written as a check in cpython course. I suspect if this behavior didn't exist it would cause issues with filenames with spaces in some cases. My sense is that this is intended behavior and not a bug.

[picnixz]

In general, if an argument contains dashes, and it should be considered an argument and not an option, it's common to use -- first, e.g., prog -- --value with --value being an argument to prog. The same can be said when one wants to remove a file that starts with --, one needs to write rm -- --thefile instead of rm --thefile.

In particular:

>>> parser.parse_args(["--", "--timeout", "1"])
Namespace(tags=['--timeout', '1'])

gives you what you expect I guess.

[qris]

@a12k thanks but I was hoping that if the argument started with — then it would be considered an option even if it contains a space. I don’t know why this special case is there, I can look for a test or commit message that might explain more.

@picnixz thanks but I want the opposite, I want it to be detected as an option (possibly an invalid one, such as in this example) rather than treated as a positional argument.

[picnixz]

If you want it to be detected as an option, why don't you use parser.add_argument("--timeout")? If it's for a general approach where you want any input of the form --<word> to be detected as an option, I'm afraid it's not supported. Also, it's the expected behavior of nargs='*' as you want to gobble all inputs into tags. But for those starting with -- you'll need to first pass -- to be sure that they are no more treated as a possible option.

[qris]

@picnixz that wouldn’t work: because the value contains a space, it will never be detected as an option.

[picnixz]

Please, indicate what you want to do. What is your input, what is expected output? what do you mean "the value contains a space"? and what do you want to be detected as an "option"?

[a12k]

@a12k thanks but I was hoping that if the argument started with — then it would be considered an option even if it contains a space. I don’t know why this special case is there, I can look for a test or commit message that might explain more.

Not saying it's necessarily the reason for the rule, but in the following case removing the check would cause an issue:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("filename", help="The file to process")
parser.add_argument("--timeout", type=int, help="Stop after N seconds")
args = parser.parse_args()

Assume you have a file on your hard drive named literally --timeout 1 and pass it to the argparser as the positional argument for the filename expecting process_file.py to parse it:

python process_file.py " --timeout 1"

In the current case the input to sys.argv would be read as a file, and correctly parsed (and your file is processed). In the case where this behavior is "fixed," argparse would parse as the timeout being 1 with a missing positional argument (the weird file named --timeout 1) and not work correctly.

[qris]

@picnixz as in the bug description, I expected that an argument starting with two dashes would be treated as an option (and if it was not a recognised, that would raise an exception) rather than being silently treated as a positional argument (in this case, because it contained a space). The example in the bug report shows that this already happens except in some weird case, apparently when the argument contains a space.

@a12k that's not quite the case I was arguing for, because --timeout 1 does not start with two dashes, it starts with a space. If I wanted to force an argument starting with -- to be treated as a positional argument in the getopt tradition, I would have to place a bare -- argument before it in the command line. I know that argparse is not getopt and does not have to obey its conventions, and that trick may not even work for argparse, but the differential treatment of arguments containing spaces is very surprising to me, coming from a getopt background.

[picnixz]

Well this is not the behavior of argparse. The reason it is treated as an argument is because you asked for it by defining a tags argument with nargs being '*'.

Maybe it is because you are using parse_args() directly but it is meant to be used with sys.args. As such, your examples are not equivalent because it depends on how the lexer splits the CLI args.

If you want to change the behaviour of argparse for that it would be a new feature which must be discussed on https://discuss.python.org/c/ideas/6. I would strongly advise you to show examples with a CLI and what you would expect. Not just showing what we currently have or explaining only with words.

For that reason I am going to close this one. Please continue the discussion on discuss as we do not have anytthing actionable here.