python/cpython · error

Argument expected for the %ls options\n

Error message

Argument expected for the %ls options\n

What it means

Emitted by CPython's command-line parser (_PyOS_GetOpt in Python/getopt.c) when a long option that requires an argument (e.g. --check-hash-based-pycs) is passed as the last command-line token with no argument following it. The parser walks argv, finds the option in its long-option table with has_arg set, but _PyOS_optind >= argc so there is nothing left to consume. The option letter '_' is then returned, which the caller treats as an unknown/bad option.

Source

Thrown at Python/getopt.c:127

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

    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;

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Supply the required argument as the next token or with '=' syntax: `python --check-hash-based-pycs=default`
2. If the value comes from a variable, quote it and verify it is non-empty before invoking python: `[ -n "$PYC_MODE" ] && python --check-hash-based-pycs="$PYC_MODE"`
3. Check `python -h` (or the usage output printed on failure) to confirm which long options require arguments

Example fix

# before
python --check-hash-based-pycs "$PYC_MODE"   # $PYC_MODE unset -> error
# after
python --check-hash-based-pycs "${PYC_MODE:-default}"

# bash: ensure long-option values are non-empty before invoking python
[ -n "$PYC_MODE" ] || PYC_MODE=default
python --check-hash-based-pycs="$PYC_MODE" app.py

When it happens

Trigger: Running the interpreter with a trailing long option that takes an argument but omitting the value, e.g. `python --check-hash-based-pycs` with nothing after it. Any -X style long option registered in the option table (has_arg != 0) whose argument would need to be argv[_PyOS_optind] when optind already equals argc.

Common situations: Shell scripts where the option value comes from an unset variable that expands to nothing (`python --check-hash-based-pycs "$PYC_MODE"` with PYC_MODE empty/absent); CI wrappers appending flags dynamically; typos that detach the value from the option.

Related errors

• Expected long option\n
• Unknown option: %ls\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/90d7b478db9289b8. Report an issue: GitHub.