What causes "Cannot install build dependencies" in pypa/pip?

Read the captured log lines printed above the error to identify which specific build dependency failed.

pypa/pip · error · BuildDependencyInstallError

failed-build-dependency-install

failed-build-dependency-install

Error message

Cannot install build dependencies

What it means

Raised by InprocessBuildEnvironmentInstaller.install() when a DiagnosticPipError (a structured pip error) occurs while installing build dependencies (PEP 518/PEP 517 build-system requirements) inside the in-process installer. The original error is wrapped into BuildDependencyInstallError with a 'reference' code of 'failed-build-dependency-install'. This path is used when --use-feature=inprocess-build-deps is enabled.

Source

Thrown at src/pip/_internal/build_env/installer.py:245

            capture_ctx: ContextManager[StringIO] = capture_logging()
            spinner: ContextManager[None] = open_rich_spinner(f"Installing {kind}")
        else:
            # Otherwise, pass-through all logs (with a header).
            capture_ctx, spinner = nullcontext(StringIO()), nullcontext()
            logger.info("Installing %s ...", kind)

        try:
            self._level += 1
            with spinner, capture_ctx as stream:
                self._install_impl(requirements, prefix)

        except DiagnosticPipError as exc:
            # Format similar to a nested subprocess error, where the
            # causing error is shown first, followed by the build error.
            logger.info(textwrap.dedent(stream.getvalue()))
            logger.error("%s", exc, extra={"rich": True})
            logger.info("")
            raise BuildDependencyInstallError(
                for_req, requirements, cause=exc, log_lines=None
            )

        except Exception as exc:
            logs: list[str] | None = textwrap.dedent(stream.getvalue()).splitlines()
            if not capture_logs:
                # If logs aren't being captured, then display the error inline
                # with the rest of the logs.
                logs = None
                if isinstance(exc, PipError):
                    logger.error("%s", exc)
                else:
                    logger.exception("pip crashed unexpectedly")
            raise BuildDependencyInstallError(
                for_req, requirements, cause=exc, log_lines=logs
            )

        finally:

View on GitHub (pinned to d7d0d0a394)

Solutions

Read the captured log lines printed above the error to identify which specific build dependency failed.
Temporarily switch back to subprocess isolation by removing `--use-feature=inprocess-build-deps` to get a cleaner subprocess error.
Check `--build-constraint` files for overly restrictive pins that conflict with build-system.requires.
Ensure network/index access is working for the build dependencies (not just the target package).
Update the failing build dependency or the package's pyproject.toml if you control it.

Example fix

# before
pip install --use-feature=inprocess-build-deps mypkg

# after (isolate the failure)
pip install mypkg
# then inspect which build dep failed and constrain accordingly

Defensive patterns

Strategy: try-catch

Validate before calling

# Before installing, verify build deps are resolvable:
# pip install --dry-run --use-feature=inprocess-build-deps <pkg>

Try / catch

from pip._internal.exceptions import BuildDependencyInstallError
try:
    # your install logic
except BuildDependencyInstallError as e:
    # e.reference == 'failed-build-dependency-install'
    print(f"Build dep install failed: {e.context}")
    # fall back to subprocess isolation

Prevention

Avoid --use-feature=inprocess-build-deps unless you need it; default subprocess isolation has better error messages.
Keep build constraints files minimal and test them separately.
Monitor pip logs with -v to catch build dependency resolution issues early.

When it happens

Trigger: Using `pip install --use-feature=inprocess-build-deps <package>` where the package has a pyproject.toml declaring build-system requirements, and one of those build dependencies fails to install (e.g., resolution conflict, network error, or the build dep itself has a broken wheel). The DiagnosticPipError is caught at installer.py:239 and re-raised as BuildDependencyInstallError at line 245.

Common situations: A package's build-system.requires pins a dependency version that conflicts with build constraints (--build-constraint). Network issues fetching build deps. A build dependency is yanked or has no compatible wheel. Experimenting with inprocess-build-deps feature flag.

Related errors

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