python/cpython · error

--check-hash-based-pycs must be one of 'default', 'always',

Error message

--check-hash-based-pycs must be one of 'default', 'always', or 'never'\n

What it means

Emitted by CPython startup (Python/initconfig.c, config_parse_cmdline) when the value given to --check-hash-based-pycs is not one of the three accepted strings 'default', 'always', or 'never'. After printing the message the interpreter prints usage and exits with status 2 via _PyStatus_EXIT(2), before any user code runs.

Source

Thrown at Python/initconfig.c:3148

            }
            break;
        }

        switch (c) {
        // Integers represent long options, see Python/getopt.c
        case 0:
            // check-hash-based-pycs
            if (wcscmp(_PyOS_optarg, L"always") == 0
                || wcscmp(_PyOS_optarg, L"never") == 0
                || wcscmp(_PyOS_optarg, L"default") == 0)
            {
                status = PyConfig_SetString(config, &config->check_hash_pycs_mode,
                                            _PyOS_optarg);
                if (_PyStatus_EXCEPTION(status)) {
                    return status;
                }
            } else {
                fprintf(stderr, "--check-hash-based-pycs must be one of "
                        "'default', 'always', or 'never'\n");
                config_usage(1, program);
                return _PyStatus_EXIT(2);
            }
            break;

        case 1:
            // help-all
            config_complete_usage(program);
            return _PyStatus_EXIT(0);

        case 2:
            // help-env
            config_envvars_usage();
            return _PyStatus_EXIT(0);

        case 3:
            // help-xoptions

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Use one of the exact tokens: default, always, or never — e.g. `python --check-hash-based-pycs=always script.py`
2. Validate the value in wrapper scripts before launching python
3. Note the equivalent env/config knob: sys.flags.check_hash_pycs_mode and PYTHONPYCACHEPREFIX alternatives for cache-control use cases

Example fix

# before
python --check-hash-based-pycs=on script.py
# after
python --check-hash-based-pycs=always script.py

# bash
MODE="${PYC_MODE:-default}"
case "$MODE" in default|always|never) ;; *) echo "bad mode: $MODE" >&2; exit 2;; esac
python --check-hash-based-pycs="$MODE" app.py

When it happens

Trigger: Running `python --check-hash-based-pycs=sometimes script.py` or `--check-hash-based-pycs always/never` (invalid token). Any value failing the wcscmp checks against L"always", L"never", L"default".

Common situations: Misremembering the allowed values (e.g. 'true'/'false', '1'/'0'); passing an empty variable; configuration copied from tools with different vocabulary; shell scripts forwarding a user-provided mode string unchecked.

Related errors

• Argument expected for the %ls options\n
• invalid nargs value
• invalid choice: %(value)r (choose from %(choices)s)
• posix_spawnattr_setbinpref failed to copy\n
• %s

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