{"id":"d35c65636dca6fce","repo":"pypa/pip","slug":"failed-build-dependency-install","errorCode":"failed-build-dependency-install","errorMessage":"Cannot install build dependencies","messagePattern":"Cannot install build dependencies","errorType":"exception","errorClass":"BuildDependencyInstallError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/build_env/installer.py","lineNumber":245,"sourceCode":"            capture_ctx: ContextManager[StringIO] = capture_logging()\n            spinner: ContextManager[None] = open_rich_spinner(f\"Installing {kind}\")\n        else:\n            # Otherwise, pass-through all logs (with a header).\n            capture_ctx, spinner = nullcontext(StringIO()), nullcontext()\n            logger.info(\"Installing %s ...\", kind)\n\n        try:\n            self._level += 1\n            with spinner, capture_ctx as stream:\n                self._install_impl(requirements, prefix)\n\n        except DiagnosticPipError as exc:\n            # Format similar to a nested subprocess error, where the\n            # causing error is shown first, followed by the build error.\n            logger.info(textwrap.dedent(stream.getvalue()))\n            logger.error(\"%s\", exc, extra={\"rich\": True})\n            logger.info(\"\")\n            raise BuildDependencyInstallError(\n                for_req, requirements, cause=exc, log_lines=None\n            )\n\n        except Exception as exc:\n            logs: list[str] | None = textwrap.dedent(stream.getvalue()).splitlines()\n            if not capture_logs:\n                # If logs aren't being captured, then display the error inline\n                # with the rest of the logs.\n                logs = None\n                if isinstance(exc, PipError):\n                    logger.error(\"%s\", exc)\n                else:\n                    logger.exception(\"pip crashed unexpectedly\")\n            raise BuildDependencyInstallError(\n                for_req, requirements, cause=exc, log_lines=logs\n            )\n\n        finally:","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/build_env/installer.py#L227-L263","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\npip install --use-feature=inprocess-build-deps mypkg\n\n# after (isolate the failure)\npip install mypkg\n# then inspect which build dep failed and constrain accordingly","handlingStrategy":"try-catch","validationCode":"# Before installing, verify build deps are resolvable:\n# pip install --dry-run --use-feature=inprocess-build-deps <pkg>","typeGuard":null,"tryCatchPattern":"from pip._internal.exceptions import BuildDependencyInstallError\ntry:\n    # your install logic\nexcept BuildDependencyInstallError as e:\n    # e.reference == 'failed-build-dependency-install'\n    print(f\"Build dep install failed: {e.context}\")\n    # fall back to subprocess isolation\n","preventionTips":["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."],"tags":["build-isolation","pep517","pep518","dependencies","inprocess-build-deps"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}