{"id":"c6ded47daaa60b55","repo":"pypa/pip","slug":"failed-wheel-build-for-install-c6ded4","errorCode":"failed-wheel-build-for-install","errorMessage":"Failed to build installable wheels for some pyproject.toml based projects","messagePattern":"Failed to build installable wheels for some pyproject\\.toml based projects","errorType":"exception","errorClass":"InstallWheelBuildError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/commands/install.py","lineNumber":531,"sourceCode":"            else:\n                # If we're not replacing an already installed pip,\n                # we're not modifying it.\n                modifying_pip = pip_req.satisfied_by is None\n            protect_pip_from_modification_on_windows(modifying_pip=modifying_pip)\n\n            reqs_to_build = [\n                r for r in requirement_set.requirements_to_install if not r.is_wheel\n            ]\n\n            _, build_failures = build(\n                reqs_to_build,\n                wheel_cache=wheel_cache,\n                verify=True,\n                allow_editables=True,\n            )\n\n            if build_failures:\n                raise InstallWheelBuildError(build_failures)\n\n            to_install = resolver.get_installation_order(requirement_set)\n\n            # Check for conflicts in the package set we're installing.\n            conflicts: ConflictDetails | None = None\n            should_warn_about_conflicts = (\n                not options.ignore_dependencies and options.warn_about_conflicts\n            )\n            if should_warn_about_conflicts:\n                conflicts = self._determine_conflicts(to_install)\n\n            # Don't warn about script install locations if\n            # --target or --prefix has been specified\n            warn_script_location = options.warn_script_location\n            if options.target_dir or options.prefix_path:\n                warn_script_location = False\n\n            # Warn on late imports so we don't silently pick up a module","sourceCodeStart":513,"sourceCodeEnd":549,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/commands/install.py#L513-L549","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before — build isolation disabled, deps missing\npip install --no-build-isolation regex\n# after — let pip resolve build deps in isolation\npip install regex","handlingStrategy":"try-catch","validationCode":"import subprocess, sys\n# Pre-flight: check for a compatible prebuilt wheel on PyPI before attempting source build\n# (simple heuristic: query the JSON API for files matching the platform tag)\nimport urllib.request, json\nproj = 'regex'\nurl = f'https://pypi.org/pypi/{proj}/json'\ndata = json.load(urllib.request.urlopen(url))\nhave_wheel = any(f['filename'].endswith('.whl') for f in data.get('urls', []))\nprint('prebuilt wheel available' if have_wheel else 'may require source build')","typeGuard":null,"tryCatchPattern":"import subprocess\ntry:\n    subprocess.run(['pip','install','regex'], check=True)\nexcept subprocess.CalledProcessError as e:\n    if e.returncode == 1 and 'Failed to build' in (e.stdout or ''):\n        # fallback: install build deps, or pin to a wheel-bearing version\n        print('wheel build failed; install gcc/python3-dev or pin a compatible version')","preventionTips":["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."],"tags":["pip","install","wheel-build","pep517","build-failure"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}