python/cpython · error

Unknown option: %ls\n

Error message

Unknown option: %ls\n

What it means

Command-line parse error from CPython's internal getopt (Python/getopt.c): an argument of the form '--name' did not match any entry in the interpreter's long-option table (the wcscmp loop over longopts found no match). It prints 'Unknown option: <arg>' and returns '_', so the interpreter reports the unrecognized option and exits.

Source

Thrown at Python/getopt.c:117

        return -1;

    if (option == L'-') {
        // Parse long option.
        if (*opt_ptr == L'\0') {
            if (_PyOS_opterr) {
                fprintf(stderr, "Expected long option\n");
            }
            return -1;
        }
        *longindex = 0;
        const _PyOS_LongOption *opt;
        for (opt = &longopts[*longindex]; opt->name; opt = &longopts[++(*longindex)]) {
            if (!wcscmp(opt->name, opt_ptr))
                break;
        }
        if (!opt->name) {
            if (_PyOS_opterr) {
                fprintf(stderr, "Unknown option: %ls\n", argv[_PyOS_optind - 1]);
            }
            return '_';
        }
        opt_ptr = L"";
        if (!opt->has_arg) {
            return opt->val;
        }
        if (_PyOS_optind >= argc) {
            if (_PyOS_opterr) {
                fprintf(stderr, "Argument expected for the %ls options\n",
                        argv[_PyOS_optind - 1]);
            }
            return '_';
        }
        _PyOS_optarg = argv[_PyOS_optind++];
        return opt->val;
    }

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Check the flag exists: `python3 --help` lists valid options
2. Fix the typo or drop unsupported '='-forms (use `python3 -W default`, `-X dev`, etc.)
3. If the flag is version-specific, guard the command per interpreter version
4. For your own argument parsing, use argparse inside the script rather than hoping python parses custom flags

Example fix

# before
python3 --verbose2 script.py   # Unknown option

# after
python3 -v script.py             # valid short option
# or
python3 -X dev script.py         # use documented long forms via -X

# shell: verify flags before running
# for f in --check --verbose2; do python3 "$f" --help >/dev/null 2>&1 || { echo "bad flag: $f"; exit 1; }; done 2>/dev/null || true
# simplest: python3 --help >/dev/null && python3 -c 'import sys; sys.exit(0)'

When it happens

Trigger: Passing a long flag python does not define, e.g. `python3 --verbose=2` where no '=' form is supported, `--version3`, or flags from another interpreter (like `--check`); also typos such as `--versio`.

Common situations: Assuming GNU-style abbreviations or flags from other tools work on python; scripts porting from `node`/`ruby` idioms; CI scripts with a typo'd flag failing immediately; using options that only exist in newer/older Python versions.

Related errors

• Expected long option\n
• Argument expected for the %ls options\n
• Unknown option: -%c\n
• Argument expected for the -%c option\n
• --check-hash-based-pycs must be one of 'default', 'always',

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