How to Fix: pip ‘Could not build wheels for …’ Error

Quick Fix

Most of the time this is caused by outdated packaging tools. Open your terminal and run:

1. python -m pip install --upgrade pip setuptools wheel
2. Re-run the failed install command, for example: pip install package-name

If it still fails, scroll up in the terminal output to the real error above the 'Could not build wheels' line - it usually names a missing compiler or system library, which the fixes below address.

Step-by-Step Guide

What this error means

pip tries to install packages using pre-built 'wheel' files (.whl) whenever possible, since these need no compiling. When you run pip install, pip first looks for a pre-compiled binary distribution called a wheel file on PyPI that matches your operating system, architecture, and Python version, and if a suitable wheel is found, installation is usually quick and easy.

If no wheel is available, pip attempts to download the package source distribution and build it locally, which often involves compiling C, C++, or Fortran code requiring specific compilers and development headers. The error means pip attempted to build a wheel from a PEP 517 project, but the wheel build failed, most likely because pip could not download a compatible wheel, so it tried to build one from source and that build failed. Crucially, for PEP 517/518 projects, pip builds a wheel using the project's declared build backend, and if the wheel build fails, pip cannot proceed with installation because it doesn't fall back to legacy setup.py install for those projects.

The real cause is almost never on the 'Could not build wheels' line itself - the most important information is often found above these final ERROR lines, in the output from the build subprocess itself. Scroll up in your terminal to find it before trying advanced fixes.

Fix 1: Upgrade pip, setuptools, and wheel

1. Upgrade your core tools. Old versions of pip, setuptools, or wheel can cause compatibility issues during wheel building. Run: python -m pip install --upgrade pip setuptools wheel
2. Confirm wheel is installed. Pip needs the wheel library to build wheels, and if wheel isn't installed, pip may fail to create the wheel. Run: pip install wheel
3. Retry the install of the original package.

Fix 2: Install the missing compiler and system build tools

1. Identify the platform-specific requirement. This means installing the necessary system-level compilers and development libraries: C++ build tools on Windows, build-essential/python3-dev on Linux, or Xcode tools on macOS.
2. On Linux (Debian/Ubuntu), run: sudo apt-get update && sudo apt-get install build-essential python3-dev. This installs the compiler and Python development headers required for compiling C extensions.
3. On Windows, install the 'Desktop development with C++' workload via Visual Studio Build Tools, since packages needing a C/C++ extension look for cl.exe.
4. On macOS, install Xcode command line tools by running: xcode-select --install
5. If the package needs Rust (some newer packages like tokenizers or cryptography do), install Rust via rustup on most platforms and retry.
6. Retry the install after the toolchain is in place.

Fix 3: Check for a supported Python version or an available wheel

1. Check PyPI for wheel availability. Check the 'Download files' section for available wheel files, for example cp39 means CPython 3.9, cp310 for 3.10, and so on.
2. Match your Python version. If no prebuilt wheel exists for your Python version, consider using a supported Python version - very new Python releases often lack wheels for some packages for a few months.
3. Try an older or pinned package version that is known to ship a wheel: pip install "package-name==known-good-version"
4. Try the --pre flag to include pre-release builds, since a pre-release version of the package might have a wheel available for your version of Python.

Fix 4: Clear cache, use verbose logging, and isolate in a virtual environment

1. Reinstall without cache. The --no-cache-dir flag disables pip's cache, which can sometimes help if a cached (and possibly corrupted) build is causing issues. Run: pip install --no-cache-dir package-name
2. Get detailed logs. Run pip install -v package-name to see exactly which build step is failing, since re-running the install with verbose output helps confirm a wheel is built and installed successfully, and explains what pip is trying to do at the moment the error appears.
3. Use a clean virtual environment to rule out conflicting packages: python3 -m venv venv, then activate it and retry the install.
4. Check for a package-specific prerequisite. Some packages need an external library installed first (for example python-ldap or pyaudio need system dev headers, and pycairo needs a cairo development package). Check the package's PyPI page for a 'prerequisites' or 'installation' section.

Fix 5: When to seek more specific help

1. Read the actual compiler error above the final 'Could not build wheels' message - it usually names a missing library, header, or command (like gcc or cl.exe failing).
2. Search for that specific package name and error together (e.g. 'Failed building wheel for numpy') since many packages have unique, documented fixes.
3. Check the package's own GitHub Issues page if the error persists - maintainers often have a pinned issue for known build problems on certain OS/Python combos.
4. If you are on an unusual platform (Apple Silicon Mac, ARM Linux, very new Python release), this is often a known compatibility gap rather than something on your end - wait for an updated wheel or use Conda/a Docker image with prebuilt binaries instead.