{"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/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/commands/wheel.py#L157-L178","documentation":"Raised as CommandError in WheelCommand.run() at wheel.py:174-175 when build_failures is non-empty after the build() call (wheel.py:154-159) and after attempting to copy successful wheels (wheel.py:160-173). It means one or more requirements could not be built into a wheel archive, including cases where a successfully built wheel could not be copied to the target wheel-dir (those are appended to build_failures at wheel.py:173).","triggerScenarios":"Running 'pip wheel <req>' where <req> has no prebuilt wheel and its PEP 517 build fails (missing build deps, compiler errors, broken backend), or where the output wheel-dir is not writable / disk-full so shutil.copy fails.","commonSituations":"Building wheels for offline distribution on a machine lacking build tools; --no-build-isolation with missing build requirements; targeting a read-only or out-of-space -w directory; pinning a source distribution with a broken setup.","solutions":["Read the per-requirement build error printed above this line — it names the failing project and the compiler/backend error.","Install system build prerequisites (compiler, python-dev headers, libffi, etc.).","Remove --no-build-isolation or pre-install the project's build dependencies.","Ensure the -w/--wheel-dir is writable and has free disk space.","Pin to a package version that ships a wheel for your platform, or build on a compatible platform."],"exampleFix":"# before — wheel-dir not writable, deps missing\npip wheel --no-build-isolation -w /readonly regex\n# after\npip wheel -w ./wheels regex","handlingStrategy":"try-catch","validationCode":"import os, sys\n# Pre-flight: ensure wheel-dir is writable and has space\nwdir = '.'\nfor i,a in enumerate(sys.argv):\n    if a in ('-w','--wheel-dir') and i+1 < len(sys.argv):\n        wdir = sys.argv[i+1]\n    elif a.startswith('--wheel-dir='):\n        wdir = a.split('=',1)[1]\nwritable = os.access(os.path.dirname(os.path.abspath(wdir)) or '.', os.W_OK)\nif not writable:\n    print(f'ERROR: wheel-dir {wdir} is not writable', file=sys.stderr)\n    sys.exit(2)","typeGuard":null,"tryCatchPattern":"import subprocess\ntry:\n    subprocess.run(['pip','wheel','-w','./wheels','regex'], check=True)\nexcept subprocess.CalledProcessError:\n    # fallback: install build deps or pin to a wheel-bearing version\n    print('wheel build failed; check build deps and disk space, or pin a prebuilt wheel')","preventionTips":["Ensure build tools and Python headers are installed before building wheels from source.","Verify the -w output directory is writable and has free disk space.","Avoid --no-build-isolation unless build requirements are pre-installed.","Read the per-project build error above the summary line for root cause."],"tags":["pip","wheel","build-failure","pep517","filesystem"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}