python/cpython · error · ArgumentError

ignored explicit argument %r

Error message

ignored explicit argument %r

What it means

When argparse splits a bundled single-dash option string (e.g. -xy where -x takes no arguments), it refuses an explicit argument attached to the zero-arg option: if an '=' separator was used (-x=3) or the remainder starts with another prefix character (-x-y), it raises ArgumentError with the ignored value. This guards the option-bundling path where each remaining character is meant to be a further option, not a value.

Source

Thrown at Lib/argparse.py:2311

                    return start_index + 1

                # if there is an explicit argument, try to match the
                # optional's string arguments to only this
                if explicit_arg is not None:
                    arg_count = match_argument(action, 'A')

                    # if the action is a single-dash option and takes no
                    # arguments, try to parse more single-dash options out
                    # of the tail of the option string
                    chars = self.prefix_chars
                    if (
                        arg_count == 0
                        and option_string[1] not in chars
                        and explicit_arg != ''
                    ):
                        if sep or explicit_arg[0] in chars:
                            msg = _('ignored explicit argument %r')
                            raise ArgumentError(action, msg % explicit_arg)
                        action_tuples.append((action, [], option_string))
                        char = option_string[0]
                        option_string = char + explicit_arg[0]
                        optionals_map = self._option_string_actions
                        if option_string in optionals_map:
                            action = optionals_map[option_string]
                            explicit_arg = explicit_arg[1:]
                            if not explicit_arg:
                                sep = explicit_arg = None
                            elif explicit_arg[0] == '=':
                                sep = '='
                                explicit_arg = explicit_arg[1:]
                            else:
                                sep = ''
                        else:
                            extras.append(char + explicit_arg)
                            extras_pattern.append('O')
                            stop = start_index + 1

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Remove the attached value: write the bare flag (-v) and pass the value to an option that accepts one.
2. If the option should take a value, give it nargs/type (e.g. add_argument('-v', type=int)) so arg_count is not 0.
3. Use the double-dash long form with '=' only for options that accept exactly one argument.

Example fix

# before
parser.add_argument('-v', action='store_true')
parser.parse_args(['-v=3'])  # error: ignored explicit argument '3'

# after
parser.add_argument('-v', action='store_true')
parser.parse_args(['-v'])

import re

def has_bad_inline_short(argv, flag_names):
    # flags declared with nargs==0, e.g. store_true
    pat = re.compile(r'^-(?!-)([A-Za-z])(?:=(.+)|(-.+))?$')
    for tok in argv:
        m = pat.match(tok)
        if m and m.group(1) in flag_names:
            return tok  # e.g. -v=3 or -v-x
    return None

try:
    args = parser.parse_args(argv)
except argparse.ArgumentError as e:
    if 'ignored explicit argument' in str(e):
        print('short flags take no =value; pass values to a value-taking option')

When it happens

Trigger: A zero-argument (arg_count == 0) single-dash option is given an attached explicit value: `-v=3` where -v is store_true, or `-v-x` where the tail begins with a prefix character. Only fires for single-dash options whose second character is not itself a prefix char (i.e. short flags, not long --options).

Common situations: Users accustomed to `--flag=value` syntax applying it to short boolean flags (-v=true); scripts that join a flag and its 'value' with '='; typos like -n=-1 where -n is a flag.

Related errors

• invalid nargs value
• .__call__() not defined
• invalid option name {option_string!r} for BooleanOptionalAct
• nargs for store actions must be != 0; if you have nothing to
• nargs must be %r to supply const

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/2d24b8322695c82d. Report an issue: GitHub.