python/cpython · error

Unknown option: -%c\n

Error message

Unknown option: -%c\n

What it means

Emitted by CPython's getopt replacement (Python/getopt.c) when a short option character is not found in the SHORT_OPTS string (wcschr returns NULL). The interpreter does not recognize that flag letter, so it prints 'Unknown option: -X' and returns '_', causing command-line parsing to fail with a usage message.

Source

Thrown at Python/getopt.c:138

        }
        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;
    }

    if ((ptr = wcschr(SHORT_OPTS, option)) == NULL) {
        if (_PyOS_opterr) {
            fprintf(stderr, "Unknown option: -%c\n", (char)option);
        }
        return '_';
    }

    if (*(ptr + 1) == L':') {
        if (*opt_ptr != L'\0') {
            _PyOS_optarg  = opt_ptr;
            opt_ptr = L"";
        }

        else {
            if (_PyOS_optind >= argc) {
                if (_PyOS_opterr) {
                    fprintf(stderr,
                        "Argument expected for the -%c option\n", (char)option);
                }
                return '_';
            }

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Run `python -h` to list valid options for the exact interpreter in use and correct the flag
2. Check for version drift: the flag may exist only in newer/older CPython (consult the version's command-line docs)
3. Look for typos or shell-quoting artifacts that mangled the option character

Example fix

# before
python -Bd -uq script.py   # -q is not a CPython option
# after
python -Bd -u script.py

# Validate flags against the running interpreter before launch
python -h 2>&1 | grep -q -- '-u' || { echo 'unsupported flag'; exit 1; }

When it happens

Trigger: Passing a single-character option that CPython does not implement, e.g. `python -z script.py`, or a bundled short-option group containing an invalid letter (e.g. `-vq` if one letter is unsupported), or using an option spelling meant for a different tool/version (e.g. a flag removed or renamed between Python versions).

Common situations: Copy-pasting a command written for a different Python version or another interpreter (PyPy, Python 2) that supported different flags; typos like `-Ve` instead of `-V`; scripts that assume a flag exists without checking the Python version.

Related errors

• Expected long option\n
• Unknown option: %ls\n
• Argument expected for the %ls options\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/3ca4eec98ddfe3a6. Report an issue: GitHub.