pip build ai_generated true

Failed building wheel for X

ID: pip/build-wheel-failed

Also available as: JSON · Markdown
78%Fix Rate
83%Confidence
33Evidence
2018-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
23 active — — —
23 active — — —

Root Cause

Wheel build failures on Linux ARM64 are predominantly caused by missing C/C++ build tools and development headers, or by packages that do not publish prebuilt ARM64 wheels on PyPI. ARM64 Linux has significantly fewer prebuilt wheels available compared to x86_64, forcing pip to compile from source distributions which requires build dependencies.

generic

Workarounds

  1. 82% success Install C/C++ build tools and Python development headers 
    On Debian/Ubuntu: 'sudo apt-get install build-essential python3-dev libffi-dev libssl-dev'. On RHEL/Fedora: 'sudo dnf install gcc gcc-c++ python3-devel libffi-devel openssl-devel'. Then retry 'pip install <package>'. For specific packages, check their documentation for additional system dependencies (e.g., numpy needs BLAS: 'sudo apt-get install libopenblas-dev').

    Sources: https://pip.pypa.io/en/stable/cli/pip_install/

  2. 65% success Use piwheels or find prebuilt ARM64 wheels 
    For Raspberry Pi and ARM64 Linux, piwheels.org provides prebuilt wheels: 'pip install --extra-index-url https://www.piwheels.org/simple <package>'. Alternatively, check if the package publishes ARM64 wheels on PyPI for a newer version: 'pip install --only-binary :all: <package>' to test.

    Sources: https://www.piwheels.org/

  3. 85% success Build in a multi-stage Docker build with build dependencies 
    Use a multi-stage Dockerfile: first stage installs build-essential and compiles wheels, second stage copies only the built wheels into a slim runtime image:
FROM python:3.11 AS builder
RUN apt-get update && apt-get install -y build-essential
RUN pip wheel --wheel-dir=/wheels -r requirements.txt
FROM python:3.11-slim
COPY --from=builder /wheels /wheels
RUN pip install --no-index --find-links=/wheels -r requirements.txt

    Sources: https://docs.docker.com/build/building/multi-stage/

Dead Ends

Common approaches that don't work:

  1. Running 'pip install --no-cache-dir' to force a fresh download 92% fail

    The cache is not the problem. The build fails because compilation dependencies (gcc, python3-dev, library headers) are missing from the system, or the package's C extension does not support ARM64. Re-downloading the same source distribution does not fix the build environment.

  2. Upgrading pip alone without installing build dependencies 80% fail

    While an older pip may lack support for newer wheel formats (PEP 517/518 builds), the primary cause on ARM64 is missing system-level build tools. Upgrading pip does not install gcc, python3-dev, or library headers required by C extensions.

Error Chain

Frequently confused with: