{"record":{"id":"ca3a26183463114a","repo":"pypa/pip","slug":"failed-to-build-one-or-more-wheels","errorCode":null,"errorMessage":"Failed to build one or more wheels","messagePattern":"Failed to build one or more wheels","errorType":"exception","errorClass":"CommandError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/commands/wheel.py","lineNumber":175,"sourceCode":"            verify=(not options.no_verify),\n            allow_editables=False,\n        )\n        for req in build_successes:\n            assert req.link and req.link.is_wheel\n            assert req.local_file_path\n            # copy from cache to target directory\n            try:\n                shutil.copy(req.local_file_path, options.wheel_dir)\n            except OSError as e:\n                logger.warning(\n                    \"Failed to copy built wheel %s to %s: %s\",\n                    req.name,\n                    options.wheel_dir,\n                    e,\n                )\n                build_failures.append(req)\n        if len(build_failures) != 0:\n            raise CommandError(\"Failed to build one or more wheels\")\n\n        return SUCCESS\n","sourceCodeStart":157,"sourceCodeEnd":178,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/commands/wheel.py#L157-L178","documentation":"Raised by the wheel command after the build phase completes if build_failures is non-empty. Failures accumulate from two sources: the build() call failing to produce a wheel for one or more requirements, and OSError failures when copying successfully-built wheels to the output directory. The message is generic because it aggregates potentially many distinct failures whose details are in the preceding log output.","triggerScenarios":"Running `pip wheel <pkg>` where the package's build backend fails (missing compiler, broken setup.py/pyproject.toml, incompatible build deps), or where the output directory (--wheel-dir) is not writable causing the shutil.copy to raise OSError.","commonSituations":"Building a C-extension package without a C compiler or development headers; building from an sdist whose pyproject.toml declares build deps unavailable offline; pointing --wheel-dir at a read-only or full filesystem; network-isolated builds where build dependencies cannot be fetched.","solutions":["Re-run with -v / --verbose to see the per-requirement build error that preceded this summary.","Install required build tools (compiler, dev headers) for C-extension packages, or use --prefer-binary to fetch a prebuilt wheel.","Ensure --wheel-dir points to a writable directory with adequate disk space.","If building from source with build isolation failing, inspect whether pyproject.toml build-system.requires can be satisfied (check network / index availability).","Try `pip wheel --no-build-isolation <pkg>` only if the build deps are already installed in the current environment."],"exampleFix":"# before (fails, generic message)\npip wheel numpy\n# after (verbose to see real error, prefer binary)\npip wheel -v --prefer-binary numpy","handlingStrategy":"try-catch","validationCode":"import os, shutil\n\ndef precheck_wheel_build(wheel_dir: str, prefer_binary: bool, has_compiler: bool) -> None:\n    if not os.path.isdir(wheel_dir) or not os.access(wheel_dir, os.W_OK):\n        raise RuntimeError(f'--wheel-dir {wheel_dir} is not writable')\n    if not prefer_binary and not has_compiler:\n        raise RuntimeError('No C compiler available; pass --prefer-binary to use prebuilt wheels')\n","typeGuard":null,"tryCatchPattern":"import subprocess\ntry:\n    subprocess.run(['pip', 'wheel', '-v', pkg], check=True)\nexcept subprocess.CalledProcessError:\n    # inspect verbose log, then fall back to a prebuilt wheel\n    subprocess.run(['pip', 'wheel', '--prefer-binary', pkg], check=True)\n","preventionTips":["Always pass -v so per-requirement errors surface before the generic summary.","Verify --wheel-dir is writable and has disk space.","Install build toolchains (gcc, dev headers) for C-extension packages or use --prefer-binary."],"tags":["pip","wheel","build","compilation","filesystem"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}