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 as InstallWheelBuildError in InstallCommand.run() at install.py:530-531 after the build() call (install.py:523-528) returns a non-empty build_failures list. It means pip successfully resolved requirements but one or more source distributions (PEP 517 pyproject.toml-based projects) could not be compiled into installable wheels. The exit code maps to 'failed-wheel-build-for-install'.

Source

Thrown at src/pip/_internal/commands/install.py:531

            else:
                # If we're not replacing an already installed pip,
                # we're not modifying it.
                modifying_pip = pip_req.satisfied_by is None
            protect_pip_from_modification_on_windows(modifying_pip=modifying_pip)

            reqs_to_build = [
                r for r in requirement_set.requirements_to_install if not r.is_wheel
            ]

            _, build_failures = build(
                reqs_to_build,
                wheel_cache=wheel_cache,
                verify=True,
                allow_editables=True,
            )

            if build_failures:
                raise InstallWheelBuildError(build_failures)

            to_install = resolver.get_installation_order(requirement_set)

            # Check for conflicts in the package set we're installing.
            conflicts: ConflictDetails | None = None
            should_warn_about_conflicts = (
                not options.ignore_dependencies and options.warn_about_conflicts
            )
            if should_warn_about_conflicts:
                conflicts = self._determine_conflicts(to_install)

            # Don't warn about script install locations if
            # --target or --prefix has been specified
            warn_script_location = options.warn_script_location
            if options.target_dir or options.prefix_path:
                warn_script_location = False

            # Warn on late imports so we don't silently pick up a module

View on GitHub (pinned to d7d0d0a394)

Solutions

Install the system build dependencies (gcc, python3-dev / python3-devel, libffi-dev, etc.).
Upgrade pip, setuptools, and wheel to current versions in the target environment.
Remove --no-build-isolation so pip can fetch the declared build backend in an isolated env, or pre-install the build requirements if you must keep isolation off.
Check that your Python version satisfies the project's requires-python; use a compatible interpreter or an older package version that ships a wheel.
Search PyPI for a prebuilt wheel matching your platform (manylinux/macOS) and pin to that version.
Read the full build log above the error line — the underlying compiler error is printed there.

Example fix

# before — build isolation disabled, deps missing
pip install --no-build-isolation regex
# after — let pip resolve build deps in isolation
pip install regex

Defensive patterns

Strategy: try-catch

Validate before calling

import subprocess, sys
# Pre-flight: check for a compatible prebuilt wheel on PyPI before attempting source build
# (simple heuristic: query the JSON API for files matching the platform tag)
import urllib.request, json
proj = 'regex'
url = f'https://pypi.org/pypi/{proj}/json'
data = json.load(urllib.request.urlopen(url))
have_wheel = any(f['filename'].endswith('.whl') for f in data.get('urls', []))
print('prebuilt wheel available' if have_wheel else 'may require source build')

Try / catch

import subprocess
try:
    subprocess.run(['pip','install','regex'], check=True)
except subprocess.CalledProcessError as e:
    if e.returncode == 1 and 'Failed to build' in (e.stdout or ''):
        # fallback: install build deps, or pin to a wheel-bearing version
        print('wheel build failed; install gcc/python3-dev or pin a compatible version')

Prevention

Install system build tools (gcc, python3-dev) before installing packages that compile C extensions.
Prefer pinning to package versions that ship manylinux/macOS wheels for your platform.
Let build isolation stay on (avoid --no-build-isolation) unless you pre-install build requirements.
Read the full build log; the root-cause compiler error is above the pip summary line.

When it happens

Trigger: Installing a package that has no prebuilt wheel for your platform and whose source build fails — missing C compiler, missing Python headers, broken build backend, incompatible Python version (requires-python), or missing build dependencies when --no-build-isolation is used.

Common situations: Installing numpy/scipy/pandas/lxml on a system without build tools; building against the wrong Python version; a pinned dependency whose sdist has a broken setup; corporate proxy blocking build-backend downloads under build isolation.

Related errors

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