pypa/pip · error · InstallWheelBuildError

failed-wheel-build-for-install

failed-wheel-build-for-install

Error message

Failed to build installable wheels for some pyproject.toml based projects

What it means

Raised by InprocessBuildEnvironmentInstaller._install_impl() at installer.py:289 when the build() call produces build failures for one or more pyproject.toml-based projects during in-process build dependency installation. The InstallWheelBuildError (reference: 'failed-wheel-build-for-install') lists the failed package names in its context.

Source

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

        from pip._internal.wheel_builder import build

        ireqs = [install_req_from_line(req, user_supplied=True) for req in requirements]
        ireqs.extend(self._build_constraints)

        resolver = self._make_resolver()
        resolved_set = resolver.resolve(ireqs, check_supported_wheels=True)
        self._preparer.prepare_linked_requirements_more(
            resolved_set.requirements.values()
        )

        reqs_to_build = [
            r for r in resolved_set.requirements_to_install if not r.is_wheel
        ]
        _, build_failures = build(
            reqs_to_build, self._wheel_cache, verify=True, allow_editables=True
        )
        if build_failures:
            raise InstallWheelBuildError(build_failures)

        installed = install_given_reqs(
            resolver.get_installation_order(resolved_set),
            prefix=prefix.path,
            # Hard-coded options (that should NOT be inherited).
            root=None,
            home=None,
            warn_script_location=False,
            use_user_site=False,
            # As the build environment is ephemeral, it's wasteful to
            # pre-compile everything since not all modules will be used.
            pycompile=False,
            progress_bar="off",
            # Link console scripts to the build env's interpreter, not pip's.
            script_executable=prefix.venv_executable,
        )

        env = get_environment(list(prefix.lib_dirs))

View on GitHub (pinned to d7d0d0a394)

Solutions

Install the required system build tools (gcc, python3-dev, etc.) for the failing build dependency.
Remove `--use-feature=inprocess-build-deps` so pip uses standard subprocess isolation with better error reporting.
Pre-build wheels for the failing build dependency and make them available via --find-links.
Pin the build dependency to a version that ships pre-built wheels for your platform.

Example fix

# before
pip install --use-feature=inprocess-build-deps mypkg
# build dep fails to compile from sdist

# after
pip install mypkg
# or pre-install the build dep as a wheel:
pip install wheel && pip install mypkg

Defensive patterns

Strategy: validation

Validate before calling

# Before installing, check if build deps have wheels for your platform:
# pip index versions <build-dep> --only-binary=:all:
# If no wheels, pre-install build tools (gcc, python-dev headers) first.

Try / catch

from pip._internal.exceptions import InstallWheelBuildError
try:
    # install logic
except InstallWheelBuildError as e:
    # e.reference == 'failed-wheel-build-for-install'
    failed_names = str(e.context).split(", ")
    print(f"Failed to build wheels for: {failed_names}")

Prevention

Ensure system build tools (compiler, headers) are installed for packages with C extensions.
Use --only-binary=:all: when possible to avoid source builds.
Pre-build wheels for build dependencies in CI and serve via --find-links.

When it happens

Trigger: Using `pip install --use-feature=inprocess-build-deps <package>` where a build dependency (declared in pyproject.toml's build-system.requires) is a source distribution that fails to compile/build into a wheel. The reqs_to_build list at installer.py:282-284 collects non-wheel requirements, and build() returns failures at line 285-287.

Common situations: A build dependency like an old version of setuptools, Cython, or a C-extension package fails to compile due to missing system headers/compilers. Using inprocess-build-deps where a build dependency only has an sdist on PyPI. Platform mismatch (e.g., building Linux-only deps on macOS).

Related errors

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