{"record":{"id":"c6ded47daaa60b55","repo":"pypa/pip","slug":"failed-wheel-build-for-install","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/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/commands/install.py#L513-L549","documentation":"Raised by `pip install` when one or more packages failed to build a wheel from source (pyproject.toml-based projects). InstallCommand.run at install.py:523 calls build() over reqs_to_build; if build_failures is non-empty it raises InstallWheelBuildError (a DiagnosticPipError with code 'failed-wheel-build-for-install'). The underlying causes are captured in build_failures and detailed in pip's preceding output.","triggerScenarios":"A requirement has no prebuilt wheel for the current platform/Python, so pip falls back to building from sdist; the build fails due to missing build dependencies, a broken pyproject.toml, missing system libraries, or incompatible compiler toolchain.","commonSituations":"Installing C-extension packages (e.g. numpy, lxml, psycopg2, cryptography) without wheels for the target Python/platform; missing build tools (gcc, python-dev headers, Rust for cryptography); PEP 517 build isolation disabled without the build deps installed; a broken package release on PyPI.","solutions":["Read the full build output above this error — it names the failing package and the real build error (e.g. missing compiler, missing header).","Install build prerequisites: compiler toolchain, python-dev headers, and the package's documented system deps.","Upgrade pip, setuptools, and wheel: `python -m pip install --upgrade pip setuptools wheel`.","Do not disable build isolation (--no-build-isolation) unless build deps are preinstalled.","Pin to a version of the package that ships a wheel for your platform, or use a binary distribution (e.g. manylinux wheel).","For pure build-env issues, try `pip install <pkg> --only-binary :all:` to force wheel-only (fails fast if no wheel exists)."],"exampleFix":"// before\npip install lxml   # fails building from sdist, missing libxml2\n// after\n# install system deps, then upgrade build tooling\napt-get install libxml2-dev libxslt1-dev python3-dev\npython -m pip install --upgrade pip setuptools wheel\npip install lxml","handlingStrategy":"try-catch","validationCode":"# Prefer prebuilt wheels; detect absence before installing\nimport subprocess\n\ndef has_wheel(name, index_url=None):\n    cmd = [\"pip\", \"index\", \"versions\", name, \"--json\"]\n    if index_url:\n        cmd += [\"--index-url\", index_url]\n    r = subprocess.run(cmd, capture_output=True, text=True)\n    return r.returncode == 0\n\n# Also ensure build toolchain is current\nsubprocess.run([\"python\", \"-m\", \"pip\", \"install\", \"--upgrade\", \"pip\", \"setuptools\", \"wheel\"], check=True)\n","typeGuard":null,"tryCatchPattern":"# Capture build failure and fall back to a binary-only install\nimport subprocess\ntry:\n    subprocess.run([\"pip\", \"install\", name], check=True)\nexcept subprocess.CalledProcessError:\n    # retry forcing wheels only\n    subprocess.run([\"pip\", \"install\", name, \"--only-binary\", \":all:\"], check=True)\n","preventionTips":["Keep pip, setuptools, wheel upgraded.","Install system build deps (compiler, headers) before installing C-extension packages.","Prefer --only-binary for packages you cannot build.","Do not use --no-build-isolation unless build deps are preinstalled."],"tags":["cli","pip-install","wheel-build","build-failure","native-extension","dependencies"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}