pypa/pip · error · CommandError

--build-constraint cannot be used with --no-build-isolation.

Error message

--build-constraint cannot be used with --no-build-isolation.

What it means

Raised as CommandError by check_build_constraints (cmdoptions.py:158) when --build-constraint is used together with --no-build-isolation. Build constraints are injected into the ISOLATED build environment to constrain which versions of build dependencies (setuptools, wheel, etc.) the PEP 517 backend may use. Disabling build isolation means there is no separate environment to apply those constraints to, so the two options are incompatible by design (lines 156-160).

Solutions

1. Keep build isolation enabled (remove --no-build-isolation) so --build-constraint takes effect in the isolated venv.
2. If you must disable isolation, drop --build-constraint and instead pin the build tools yourself in the active environment.

Example fix

# before
pip install --build-constraint build-constraints.txt --no-build-isolation <pkg>
# after
pip install --build-constraint build-constraints.txt <pkg>

# Reject the combination before building the command line.
def validate_build_constraint(opts):
    if opts.get("build_constraints") and not opts.get("build_isolation"):
        raise ValueError("--build-constraint requires build isolation; remove --no-build-isolation")
    return True

When it happens

Trigger: `pip install --build-constraint constraints.txt --no-build-isolation <pkg>` where constraints.txt pins build-time dependency versions.

Common situations: Hardening builds in an air-gapped/offline setup where the user also disables isolation to reuse a pre-populated environment; copy-pasting a hardened-build command and adding --no-build-isolation to speed up builds.

Related errors

• Can not use any platform or abi specific options unless…
• Cannot combine '--path' with '--user' or '--local'
• Cannot use '--only-dependencies' in combination with
• Could not locate Python interpreter
• Failed to run pip under

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/222d5e5794c03a47. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_internal/cli/cmdoptions.py:158

        from pip._internal.utils import pylock as pylock_utils

        for filename in options.requirements:
            if pylock_utils.is_valid_pylock_filename(filename):
                raise CommandError(
                    "Platform and interpreter constraints using "
                    "--python-version, --platform, --abi, or --implementation, "
                    f"are not supported when selecting requirements from {filename!r}"
                )


def check_build_constraints(options: Values) -> None:
    """Function for validating build constraints options.

    :param options: The OptionParser options.
    """
    if hasattr(options, "build_constraints") and options.build_constraints:
        if not options.build_isolation:
            raise CommandError(
                "--build-constraint cannot be used with --no-build-isolation."
            )

        # Import here to avoid circular imports
        from pip._internal.network.session import PipSession
        from pip._internal.req.req_file import get_file_content

        # Eagerly check build constraints file contents
        # is valid so that we don't fail in when trying
        # to check constraints in isolated build process
        with PipSession() as session:
            for constraint_file in options.build_constraints:
                get_file_content(constraint_file, session)


def _path_option_check(option: Option, opt: str, value: str) -> str:
    return os.path.expanduser(value)

View on GitHub (pinned to f399c37189)