pypa/pip · error · InstallationError

Some build dependencies for {requirement} conflict with {con

Error message

Some build dependencies for {requirement} conflict with {conflicting_with}: {description}.

What it means

InstallationError raised by SourceDistribution._raise_conflicts when the build backend's required dependencies (declared in [build-system] requires of pyproject.toml, or dynamically requested by the backend) are present in the build environment but at versions incompatible with what is required. It names the requirement being built, what the deps conflict with, and lists each installed-vs-wanted pair.

Source

Thrown at src/pip/_internal/distributions/sdist.py:180

                missing, "normal", kind="backend dependencies", for_req=self.req
            )

    def _raise_conflicts(
        self, conflicting_with: str, conflicting_reqs: set[tuple[str, str]]
    ) -> None:
        format_string = (
            "Some build dependencies for {requirement} "
            "conflict with {conflicting_with}: {description}."
        )
        error_message = format_string.format(
            requirement=self.req,
            conflicting_with=conflicting_with,
            description=", ".join(
                f"{installed} is incompatible with {wanted}"
                for installed, wanted in sorted(conflicting_reqs)
            ),
        )
        raise InstallationError(error_message)

    def _raise_missing_reqs(self, missing: set[str]) -> None:
        format_string = (
            "Some build dependencies for {requirement} are missing: {missing}."
        )
        error_message = format_string.format(
            requirement=self.req, missing=", ".join(map(repr, sorted(missing)))
        )
        raise InstallationError(error_message)

View on GitHub (pinned to d7d0d0a394)

Solutions

Drop --no-build-isolation so pip builds in a clean venv that resolves the declared [build-system].requires independently.
Align the offending dependency: install/upgrade the 'installed' package to a version satisfying the 'wanted' specifier, or relax the specifier in pyproject.toml's [build-system].requires.
Remove conflicting pins from any -c constraints file you passed.
Check the listed pair (installed vs wanted) and reconcile that single requirement first.

Example fix

# before - ambient env has setuptools 60 but pyproject needs >=64
# pyproject.toml
[build-system]
requires = ["setuptools>=64", "wheel"]

# fix: stop forcing the old version
pip install -U "setuptools>=64"
# or let pip isolate the build
pip install .   # (omit --no-build-isolation)

Defensive patterns

Strategy: validation

Validate before calling

from pip._internal.utils.compatibility_tags import get_supported
# before --no-build-isolation, verify build deps are satisfiable
import tomllib
with open('pyproject.toml','rb') as f: data=tomllib.load(f)
requires = data.get('build-system',{}).get('requires',[])
print('build-system requires:', requires)
# pip install each before building with --no-build-isolation

Type guard

def build_deps_compatible(installed: dict, requires: list[str]) -> bool:
    from packaging.requirements import Requirement
    from packaging.version import Version
    for r in requires:
        req = Requirement(r)
        v = installed.get(req.name)
        if v is None or not req.specifier.contains(Version(v), prereleases=True):
            return False
    return True

Try / catch

from pip._internal.exceptions import InstallationError
try:
    dist.prepare_distribution_metadata(env_installer, isolation, True, True)
except InstallationError as e:
    if 'conflict with' in str(e):
        # parse installed/wanted pairs, reconcile versions
        ...

Prevention

Avoid --no-build-isolation unless the build env is known-good.
Keep pyproject.toml [build-system].requires minimal and correct.
Do not pin build tools in constraints files used for installs.
Reproduce build deps in CI base images.

When it happens

Trigger: Triggered during prepare_distribution_metadata after build_env.check_requirements() returns a non-empty conflicting set - either from the static pyproject [build-system].requires, the PEP 517/518 requirements-to-check, or the dynamic backend dependencies returned by get_requires_for_build_wheel/editable. A dependency already pinned/installed in the environment satisfies a different version specifier than the one the build needs.

Common situations: Installing without build isolation (--no-build-isolation) so the ambient environment's packages clash with pyproject build requirements; a lockfile or constraints file pinning a build tool (setuptools/wheel/cython) to a version older/newer than the package's [build-system].requires demands; conflicting transitive build deps across two packages in one install.

Related errors

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