python install_error ai_generated true

error: subprocess-exited-with-error × python setup.py bdist_wheel did not run successfully.

ID: python/pip-subprocess-exited-with-error

Also available as: JSON · Markdown · 中文
80%Fix Rate
87%Confidence
0Evidence
2024-03-11First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
3.8 active — — —
3.9 active — — —
3.10 active — — —
3.11 active — — —
3.12 active — — —

Root Cause

A package's build backend (legacy setuptools setup.py) crashed during wheel creation, usually due to missing system C headers, an incompatible setuptools version, or a Cython/compiler failure.

generic

中文

某个包的构建后端（旧式 setuptools setup.py）在生成 wheel 时崩溃，通常由缺少系统 C 头文件、setuptools 版本不兼容或 Cython/编译器失败引起。

Workarounds

  1. 85% success 
    Install the needed system build tools first. On Debian/Ubuntu: `sudo apt-get install build-essential python3-dev libffi-dev libssl-dev`. On macOS: `xcode-select --install`. Then retry `pip install <pkg>`.
  2. 80% success 
    Prefer a prebuilt wheel: `pip install --only-binary=:all: <pkg>`, or upgrade the build toolchain with `pip install --upgrade pip setuptools wheel` before installing.
  3. 75% success 
    Read the full traceback above the error (pip truncates it). Re-run with `pip install -v <pkg>` to see the actual compiler error and address that specific missing dependency.

Dead Ends

Common approaches that don't work:

  1. 95% fail

    The build fails deterministically; retrying does not supply the missing compiler or headers.

  2. 70% fail

    Disabling isolation makes pip use the current environment's setuptools, which may be even older and fail the same way.

  3. 60% fail

    Older pip still invokes the same broken build backend and loses modern resolver features.