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 by check_build_constraints() in cmdoptions.py:158 when --build-constraint is specified together with --no-build-isolation. Build constraints are designed to control dependencies in the isolated build environment; without build isolation, there is no separate environment to constrain, making the option meaningless and potentially confusing.

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 d7d0d0a394)

Solutions

Remove --no-build-isolation to keep build isolation enabled (allows --build-constraint to work).
Remove --build-constraint if you intentionally disabled build isolation and manage build deps manually.
Pre-install the exact build dependency versions you need in your environment and drop both flags.

Example fix

# before
pip install --build-constraint build-constraints.txt --no-build-isolation mypkg

# after (choose one):
# Option A: keep build constraints, enable isolation
pip install --build-constraint build-constraints.txt mypkg
# Option B: keep no isolation, drop build constraints
pip install --no-build-isolation mypkg

Defensive patterns

Strategy: validation

Validate before calling

def validate_build_constraint_options(options):
    """Ensure --build-constraint is not used with --no-build-isolation."""
    if options.get('build_constraints') and not options.get('build_isolation', True):
        return False
    return True

Try / catch

from pip._internal.exceptions import CommandError
try:
    # pip install with build-constraint + no-build-isolation
except CommandError as e:
    if '--build-constraint' in str(e):
        # either remove --no-build-isolation or remove --build-constraint

Prevention

Understand that build constraints require an isolated build environment.
If disabling isolation, pre-install build deps manually instead.
Document your build-isolation strategy in project README.

When it happens

Trigger: Calling `pip install --build-constraint constraints.txt --no-build-isolation <pkg>`. The check at cmdoptions.py:156-160 verifies that if build_constraints are set, build_isolation must be True (the default).

Common situations: Trying to pin build dependency versions while also disabling isolation (e.g., to use pre-installed build tools). Not understanding that build constraints only apply within isolated environments. Copy-pasting flags from different pip invocations.

Related errors

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