{"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/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/resolution/resolvelib/candidates.py#L243-L279","documentation":"FailedToPrepareCandidate wraps an InstallationSubprocessError thrown while _prepare_distribution() built metadata (getegginfo/getmetadata/pep517 prepare-metadata-for-build-wheel). The package's build step failed before pip even got usable metadata, so resolution cannot continue for that candidate.","triggerScenarios":"self._prepare_distribution() raises InstallationSubprocessError (exit code from `pip pep517`/setup.py egg_info). Triggered when an sdist has no wheel and its PEP 517 backend or setup.py fails (missing build dep, compile error, network during build, incompatible Python).","commonSituations":"Installing an sdist that needs a compiler you don't have (e.g. lxml/numpy on a slim image without build-essential); a pyproject.toml backend whose wheel isn't installed in the build env; a package requiring a newer Python than the target; broken or abandoned packages whose build fails on modern setuptools.","solutions":["Read the full build log above the error to find the root cause (compile error / missing build dep / backend).","Install build prerequisites: compiler toolchain and the package's PEP 518 build-system.requires.","Prefer a prebuilt wheel: upgrade pip (so it finds manylinux tags) or pin a version that ships wheels for your platform.","If you own it, fix the build (PEP 517 backend, setup.py), then republish a wheel."],"exampleFix":"# before - sdist build fails for lack of compiler/build deps\npip install heavyextpkg==1.0\n\n# after - ensure build toolchain + upgrade pip to fetch wheels\napt-get install -y build-essential python3-dev\npython -m pip install -U pip setuptools wheel\npip install heavyextpkg==1.0","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    pip_install(req)\nexcept FailedToPrepareCandidate as e:\n    # inspect e.failed_step and the build log printed above\n    if 'prepare_metadata_for_build_wheel' in e.failed_step:\n        ensure_build_env()  # install build-system.requires + toolchain\n        pip_install(req)\n    else:\n        raise","preventionTips":["Install build-essential / python3-dev and a recent pip+setuptools+wheel before installing sdists.","Prefer wheels: pin versions that publish wheels for your platform.","In Docker images, use multi-arch base images or platform-correct wheels to avoid sdist builds."],"tags":["pip","resolvelib","build","pep517","sdist","subprocess"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}