pypa/pip · error · CommandError

--require-hashes and --no-require-hashes are mutually exclus

Error message

--require-hashes and --no-require-hashes are mutually exclusive

What it means

Raised by pip's RequirementCommand when both --require-hashes and --no-require-hashes are passed on the same invocation. These flags are logical opposites: --require-hashes forces hash-checking on every requirement, --no-require-hashes disables the auto-detection that turns on hash-checking when a requirement carries hash options. pip refuses to guess which one wins, so it aborts in build_package_finder/run flow via a CommandError.

Source

Thrown at src/pip/_internal/cli/req_command.py:431

                if not check_requires_python(
                    requires_python=script_requires_python,
                    version_info=target_python.py_version_info,
                ):
                    raise UnsupportedPythonVersion(
                        f"Script {script!r} requires a different Python: "
                        f"{target_python.py_version} not in {script_requires_python!r}"
                    )

            for req in script_metadata.get("dependencies", []):
                req_to_add = install_req_from_req_string(
                    req,
                    isolated=options.isolated_mode,
                    user_supplied=True,
                )
                requirements.append(req_to_add)

        if options.require_hashes and options.no_require_hashes:
            raise CommandError(
                "--require-hashes and --no-require-hashes are mutually exclusive"
            )

        # If any requirement has hash options, enable hash checking for all
        # requirements, unless this mechanism has been explicitly disabled
        # with --no-require-hashes.
        if not options.no_require_hashes and any(
            req.has_hash_options for req in requirements
        ):
            options.require_hashes = True

        if not (
            args
            or options.editables
            or options.requirements
            or options.dependency_groups
            or options.requirements_from_scripts
        ):

View on GitHub (pinned to d7d0d0a394)

Solutions

Inspect the full pip invocation: run with pip <cmd> -vv to see option sources, then remove either --require-hashes or --no-require-hashes.
Check pip.conf (pip config list), PIP_* environment variables, and any -r requirements files for one of the two flags and delete the conflicting one.
If you need hashes, keep --require-hashes only; if you must disable hash auto-detection, keep --no-require-hashes only.
If a wrapper script assembles flags, split the secure and legacy flag sets into mutually exclusive code paths instead of unioning them.

Example fix

// before
pip install --require-hashes --no-require-hashes -r locked.txt
// after
pip install --require-hashes -r locked.txt

Defensive patterns

Strategy: validation

Validate before calling

# Validate flag exclusivity before shelling out to pip
flags = {"--require-hashes": require_hashes, "--no-require-hashes": no_require_hashes}
if all(flags.values()):
    raise SystemExit("Cannot pass both --require-hashes and --no-require-hashes")

Prevention

Centralize hash-pinning policy in a single pip.conf or env var instead of command-line flags.
When programmatically building pip argv, assert at most one of the two flags is present before exec.

When it happens

Trigger: Invoking pip install/download/wheel with both --require-hashes and --no-require-hashes on the command line, in PIP_INSTALL_OPTS env var, in a requirements file's pip options, or in a pip.conf. The check at req_command.py:430 fires unconditionally before any resolution.

Common situations: Copy-pasting flags from two different runbooks; a wrapper script (tox, nox, CI YAML) concatenating a 'secure' hash-pinning block with a legacy --no-require-hashes block; requirements files that inherit each other via -r; setting PIP_REQUIRE_HASHES=1 in the environment while a config file also sets no-require-hashes.

Related errors

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/edcb5d7952625a5a.json. Report an issue: GitHub.