pypa/pip · error · FailedToPrepareCandidate

Failed to build '{package_name}' when {failed_step.lower()}

Error message

Failed to build '{package_name}' when {failed_step.lower()}

What it means

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.

Source

Thrown at src/pip/_internal/resolution/resolvelib/candidates.py:261

    def _prepare(self) -> BaseDistribution:
        try:
            dist = self._prepare_distribution()
        except HashError as e:
            # Provide HashError the underlying ireq that caused it. This
            # provides context for the resulting error message to show the
            # offending line to the user.
            e.req = self._ireq
            raise
        except InstallationSubprocessError as exc:
            if isinstance(self._ireq.comes_from, InstallRequirement):
                request_chain = self._ireq.comes_from.from_path()
            else:
                request_chain = self._ireq.comes_from

            if request_chain is None:
                request_chain = "directly requested"

            raise FailedToPrepareCandidate(
                package_name=self._ireq.name or str(self._link),
                requirement_chain=request_chain,
                failed_step=exc.command_description,
            )

        self._check_metadata_consistency(dist)
        return dist

    def iter_dependencies(self, with_requires: bool) -> Iterable[Requirement | None]:
        # Emit the Requires-Python requirement first to fail fast on
        # unsupported candidates and avoid pointless downloads/preparation.
        yield self._factory.make_requires_python_requirement(self.dist.requires_python)
        requires = self.dist.iter_dependencies() if with_requires else ()
        for r in requires:
            yield from self._factory.make_requirements_from_spec(str(r), self._ireq)

    def get_install_requirement(self) -> InstallRequirement | None:
        return self._ireq

View on GitHub (pinned to d7d0d0a394)

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.

Example fix

# before - sdist build fails for lack of compiler/build deps
pip install heavyextpkg==1.0

# after - ensure build toolchain + upgrade pip to fetch wheels
apt-get install -y build-essential python3-dev
python -m pip install -U pip setuptools wheel
pip install heavyextpkg==1.0

Defensive patterns

Strategy: try-catch

Try / catch

try:
    pip_install(req)
except FailedToPrepareCandidate as e:
    # inspect e.failed_step and the build log printed above
    if 'prepare_metadata_for_build_wheel' in e.failed_step:
        ensure_build_env()  # install build-system.requires + toolchain
        pip_install(req)
    else:
        raise

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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