{"record":{"id":"2c7e3ea519633a7e","repo":"pypa/pip","slug":"failed-to-build-package-name-when-failed-step","errorCode":null,"errorMessage":"Failed to build '{package_name}' when {failed_step.lower()}","messagePattern":"Failed to build '(.+?)' when (.+?)","errorType":"exception","errorClass":"FailedToPrepareCandidate","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/resolution/resolvelib/candidates.py","lineNumber":261,"sourceCode":"    def _prepare(self) -> BaseDistribution:\n        try:\n            dist = self._prepare_distribution()\n        except HashError as e:\n            # Provide HashError the underlying ireq that caused it. This\n            # provides context for the resulting error message to show the\n            # offending line to the user.\n            e.req = self._ireq\n            raise\n        except InstallationSubprocessError as exc:\n            if isinstance(self._ireq.comes_from, InstallRequirement):\n                request_chain = self._ireq.comes_from.from_path()\n            else:\n                request_chain = self._ireq.comes_from\n\n            if request_chain is None:\n                request_chain = \"directly requested\"\n\n            raise FailedToPrepareCandidate(\n                package_name=self._ireq.name or str(self._link),\n                requirement_chain=request_chain,\n                failed_step=exc.command_description,\n            )\n\n        self._check_metadata_consistency(dist)\n        return dist\n\n    def iter_dependencies(self, with_requires: bool) -> Iterable[Requirement | None]:\n        # Emit the Requires-Python requirement first to fail fast on\n        # unsupported candidates and avoid pointless downloads/preparation.\n        yield self._factory.make_requires_python_requirement(self.dist.requires_python)\n        requires = self.dist.iter_dependencies() if with_requires else ()\n        for r in requires:\n            yield from self._factory.make_requirements_from_spec(str(r), self._ireq)\n\n    def get_install_requirement(self) -> InstallRequirement | None:\n        return self._ireq","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/resolution/resolvelib/candidates.py#L243-L279","documentation":"_prepare (candidates.py:252-265) catches InstallationSubprocessError from the PEP 517 build backend (metadata generation or wheel building) and re-raises it as FailedToPrepareCandidate, surfacing the package name, the requirement chain, and the failed step (e.g. 'building wheel'). The actual build log appears above this summary error.","triggerScenarios":"The build backend subprocess exits non-zero while preparing metadata or building a wheel for a sdist requirement (missing compiler, broken setup.py, build-dep resolution failure).","commonSituations":"Missing system build tools (gcc, python-dev headers); broken pyproject.toml build backend; network failure fetching build-system.requires in isolation; syntax error in setup.py.","solutions":["Read the build backend output printed above the FailedToPrepareCandidate line for the root cause.","Install build prerequisites (build-essential, python3-dev, wheel, setuptools).","Debug with pip install --no-build-isolation to use the current env's build deps.","Pin to a version that ships prebuilt wheels to avoid building from sdist."],"exampleFix":"# before\npip install pkg   # builds from sdist, fails\n# after\npip install pkg==1.2 --only-binary :all:   # use prebuilt wheel","handlingStrategy":"try-catch","validationCode":"# Prefer prebuilt wheels; check availability before building from sdist.\nimport subprocess, sys\npkg = \"pkg\"\nr = subprocess.run([sys.executable, \"-m\", \"pip\", \"index\", \"versions\", pkg], capture_output=True, text=True)\nprint(r.stdout)  # inspect available versions; prefer --only-binary","typeGuard":null,"tryCatchPattern":"# When automating installs, catch the failure and fall back to a wheel-only install.\nimport subprocess, sys\ndef safe_install(pkg):\n    try:\n        subprocess.check_call([sys.executable, \"-m\", \"pip\", \"install\", pkg])\n    except subprocess.CalledProcessError:\n        subprocess.check_call([sys.executable, \"-m\", \"pip\", \"install\", \"--only-binary\", \":all:\", pkg])\nsafe_install(\"pkg\")","preventionTips":["Ensure build tools (gcc, python-dev, wheel, setuptools) are installed.","Use --only-binary :all: when you only want prebuilt wheels.","Read the full build log above the FailedToPrepareCandidate line."],"tags":["build","subprocess","wheel"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}