Skip to content
Tutorial Reference

How to Resolve Python "ERROR: Could not build wheels for X which use PEP 517"

Fix the 'Could not build wheels' error in Python when installing packages requiring PEP 517 builds, including missing system dependencies, outdated tools, and environment-specific solutions.

When installing Python packages using pip, you might encounter an error message like ERROR: Failed building wheel for <package-name> followed by ERROR: Could not build wheels for <package-name> which use PEP 517 and cannot be installed directly or ERROR: Could not build wheels for <package-name>, which is required to install pyproject.toml-based projects. This indicates that pip attempted to install a package, found no pre-built "wheel" file compatible with your system, and failed when trying to build the package from its source code using the modern PEP 517 build system interface.

This guide explains the common causes related to build failures (outdated tools, missing system dependencies) and provides effective solutions, including specific prerequisites for commonly problematic packages.

Understanding the Error: Wheels vs. Source Builds & PEP 517

  • Wheels (.whl files): These are pre-compiled Python packages optimized for specific platforms (OS, Python version, architecture). When available, pip prefers installing wheels because it's fast and doesn't require local build tools.
  • Source Distributions (.tar.gz, .zip): These contain the raw source code and instructions (like setup.py or pyproject.toml) on how to build the package. pip uses these if no compatible wheel is found.
  • Building from Source: This often involves compiling code written in C, C++, Rust, or other languages. It requires specific build tools (compilers, linkers) and development headers/libraries to be present on your system.
  • PEP 517: A Python standard defining how build tools (like setuptools, poetry, flit) interact with pip. It allows packages to specify their build dependencies in pyproject.toml.

The error "Could not build wheels..." means:

  1. pip couldn't find a pre-built wheel for the package compatible with your environment.
  2. It fell back to building from the source distribution.
  3. The build process (using the PEP 517 interface) failed.

Common Causes

  • Outdated Build Tools: An old version of pip, setuptools, or wheel might not fully support the PEP 517 build process required by the package.
  • Missing System Dependencies: The package requires compilation (C/C++/Rust/etc.) but the necessary compiler, Python development headers, or specific library headers (e.g., libldap-dev, portaudio19-dev) are not installed on your operating system. This is a very frequent cause.
  • Incompatible Python Version: While less common for build failures (more often causes "Could not find version..."), some build scripts might have implicit Python version dependencies.
  • Permission Issues: Less likely for build failures themselves, but can occur during installation steps.
  • Corrupted Cache or Environment: A bad cache or inconsistent virtual environment can interfere.

Solution 1: Upgrade Pip, Setuptools, and Wheel (Often Fixes Build Interface Issues)

Keeping your core packaging tools up-to-date is the first step, as newer versions have better support for PEP 517 and modern build backends.

python -m pip install --upgrade pip setuptools wheel

pip install --upgrade pip setuptools wheel
pip3 install --upgrade pip setuptools wheel

After upgrading, retry installing the problematic package.

Solution 2: Install Missing System Build Dependencies (Common for Compiled Packages)

This is the most common reason for build failures for packages involving C/C++/Rust code. You need the development tools and libraries specific to the package and your operating system.

General Build Tools (Compilers)

  • Debian/Ubuntu: sudo apt-get update && sudo apt-get install build-essential
  • Fedora/CentOS/RHEL: sudo yum groupinstall "Development Tools" or sudo dnf groupinstall "Development Tools"
  • macOS: Install Xcode Command Line Tools: xcode-select --install
  • Windows: Install Microsoft C++ Build Tools (available with Visual Studio Installer - select "Desktop development with C++").

Python Development Headers

Required for compiling C extensions for Python.

  • Debian/Ubuntu: sudo apt-get install python3-dev (or python3.x-dev for a specific version like python3.10-dev)
  • Fedora/CentOS/RHEL: sudo yum install python3-devel (or python3.x-devel)
  • macOS: Usually included with Xcode Command Line Tools or Python installed via Homebrew.
  • Windows: Included with the standard Python installer from python.org.

Package-Specific Libraries/Headers

Many packages depend on external system libraries. You MUST consult the specific package's documentation (PyPI page, GitHub README, official docs) for its prerequisites. Common examples include:

  • python-ldap: Needs OpenLDAP development libraries (libldap2-dev, libsasl2-dev on Debian/Ubuntu; openldap-devel on RedHat/CentOS).
  • PyAudio: Needs PortAudio development library (portaudio19-dev on Debian/Ubuntu; brew install portaudio on macOS).
  • xmlsec: Needs libxml2, libxmlsec1, and OpenSSL development libraries (names vary by OS, e.g., libxml2-dev, libxmlsec1-dev, libxmlsec1-openssl on Debian/Ubuntu).
  • bcrypt, tokenizers: Might require a Rust compiler (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh).

Finding Required Dependencies

  1. Read the Error Log: Carefully examine the full output from pip install. Often, the compiler errors just before the "Failed building wheel" message will name missing header files (.h) or libraries (-l...).
  2. Check Package Documentation: The installation section of the package's official documentation or PyPI page is the definitive source for prerequisites.
  3. Search Online: Search for "install <package-name> <your-operating-system> prerequisites" or "Could not build wheels for <package-name> <your-operating-system>".

Solution 3: Check Python Version Compatibility

Verify that your Python version is supported by the package version you are trying to install. Check the package's PyPI page ("Requires" section and "Download files" for available wheels). If necessary, use a different Python version (see Solution 4).

Always use virtual environments to isolate project dependencies and avoid conflicts.

python3 -m venv venv

source venv/bin/activate    # Linux/macOS
venv\Scripts\activate       # Windows

pip install --upgrade pip setuptools wheel

pip install package_name

Other Potential Fixes and Workarounds

If the above doesn't work:

  • Try Pre-release Versions (--pre): A fix might be in a development version. 
    pip install --pre package_name
  • Disable Cache (--no-cache-dir): Rules out issues with corrupted cached downloads. 
    pip install --no-cache-dir package_name
  • Try Different Package Version: A specific version might have build issues; try an older or newer one. 
    pip install package_name==1.2.3 # Install specific version
pip install "package_name<1.3"  # Install latest below 1.3
  • Try --no-use-pep517 (Legacy Fallback - Use Cautiously): This forces pip to use the older setup.py install method instead of the PEP 517 build interface. This is a temporary workaround and may fail if the package only supports PEP 517 builds. It can sometimes bypass issues if the package's pyproject.toml or build backend has problems. 
    pip install --no-use-pep517 package_name

Debugging with Verbose Output (-vvv)

Get maximum detail from pip to understand the build failure:

pip install package_name -vvv

Look closely at the compiler commands and error messages just before the final "Failed building wheel" line.

Package-Specific Prerequisites and Solutions

Often, the "Could not build wheels" error for specific packages arises from missing system-level libraries or development headers needed to compile their C/C++/Rust components. Here are common prerequisites for packages frequently causing this error. Always consult the official documentation for the specific package as requirements can change.

After installing prerequisites for your OS, remember to retry: pip install <package-name>

python-ldap

  • Debian/Ubuntu: sudo apt-get update && sudo apt-get install build-essential python3-dev libldap2-dev libsasl2-dev slapd ldap-utils
  • Fedora/CentOS/RHEL: sudo yum update && sudo yum groupinstall "Development Tools" && sudo yum install openldap-devel python3-devel (or use dnf instead of yum)
  • macOS: brew install openldap (might require setting LDFLAGS/CPPFLAGS, check python-ldap docs)
  • Alpine: apk add build-base openldap-dev python3-dev

pyaudio

  • Debian/Ubuntu: sudo apt-get update && sudo apt-get install portaudio19-dev python3-dev (use correct python3.x-dev if needed)
  • Fedora/CentOS/RHEL: sudo yum install portaudio-devel python3-devel
  • macOS: brew install portaudio then potentially brew link --overwrite portaudio
  • Windows: Usually installs via pip install pyaudio as it includes precompiled PortAudio. If issues occur, check PortAudio website/build from source (advanced).
  • Conda: conda install -c anaconda pyaudio

pycocotools

  • Linux/macOS: Requires C compiler. Often installing cython first helps: pip install cython, then pip install pycocotools.
  • Windows: Often problematic. Try installing a Windows-specific fork: pip install pycocotools-windows
  • Conda: conda install -c conda-forge pycocotools or conda install -c esri pycocotools

cx_Oracle

  • Requires Oracle Instant Client libraries and headers installed and configured correctly. See Oracle's detailed installation instructions for your OS.
  • Debian/Ubuntu: May need sudo apt-get install build-essential libaio1 before pip install cx_Oracle.
  • Conda: conda install -c anaconda cx_oracle often handles dependencies better.

scikit-learn

  • Generally requires C/C++ compiler and Python development headers (see 4.1, 4.2). Also needs NumPy and SciPy (often installed as dependencies).
  • Ensure pip, setuptools, wheel are up-to-date.
  • Conda: conda install -c anaconda scikit-learn is often easiest.

opencv-python

  • Usually installed via pre-built wheels, making build errors less common unless using an unsupported platform/Python version or trying to install opencv-python-headless alongside the main package.
  • Check Python version (64-bit, supported range, see package PyPI).
  • Ensure pip is up-to-date.
  • Conda: conda install -c conda-forge opencv
  • Linux (Rare - if building): May need system libraries like ffmpeg, libsm6, libxext6.

numpy

  • Requires C compiler and Python development headers (see 4.1, 4.2). Usually installs via wheels.
  • Ensure pip is up-to-date.
  • Conda: conda install -c anaconda numpy

cryptography

  • Requires C compiler, Python development headers, OpenSSL development headers (libssl-dev on Debian/Ubuntu, openssl-devel on Fedora/CentOS), and potentially Rust (cargo) for newer versions.
  • Conda: conda install -c anaconda cryptography

psutil

  • Requires C compiler and Python development headers. Pre-compiled wheels are usually available.
  • Ensure pip is up-to-date. If wheel fails, installing build tools (4.1, 4.2) should allow building from source.
  • Conda: conda install -c conda-forge psutil

gevent

  • Requires C compiler and Python development headers.
  • Debian/Ubuntu: sudo apt-get install python3-dev
  • Fedora/CentOS/RHEL: sudo yum install python3-devel
  • Alpine: apk add build-deps (or gcc musl-dev python3-dev libffi-dev)
  • Conda: conda install -c anaconda gevent

pycairo

  • Requires Cairo development libraries and headers, plus pkg-config.
  • Debian/Ubuntu: sudo apt-get install libcairo2-dev pkg-config python3-dev
  • Fedora/CentOS/RHEL: sudo yum install cairo-devel pkgconfig python3-devel
  • macOS: brew install cairo pkg-config
  • Conda: Often easier via conda install -c anaconda pycairo

pycuda

  • Requires C++ compiler, Python development headers, and crucially, the NVIDIA CUDA Toolkit installed and configured correctly (matching driver version). Environment variables like CUDA_ROOT might need to be set. See PyCUDA documentation for detailed setup.
  • Conda: conda install -c conda-forge pycuda might simplify dependency handling.

tokenizers (Hugging Face)

  • Requires the Rust compiler toolchain. 
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env # Or restart terminal
    Then pip install tokenizers.
  • Conda: conda install -c conda-forge tokenizers

yarl, multidict (often via discord.py, aiohttp)

  • Requires C compiler and Python development headers. Usually install via wheels.
  • Ensure pip, setuptools, wheel are up-to-date. If wheels fail, installing build tools (4.1, 4.2) allows building from source.

xmlsec

  • Requires libxml2, libxmlsec1, OpenSSL development headers, and pkg-config. Package names vary significantly by OS.
  • Debian/Ubuntu: sudo apt-get install pkg-config libxml2-dev libxmlsec1-dev libxmlsec1-openssl
  • Fedora/CentOS/RHEL: sudo yum install pkgconfig libxml2-devel xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel
  • macOS: brew install libxml2 libxmlsec1 pkg-config
  • Alpine: apk add build-base libressl-dev libffi-dev libxml2-dev xmlsec-dev
  • Windows: Often tricky. pip install xmlsec --no-binary=xmlsec might attempt to build if build tools are present, otherwise check unofficial binaries or conda.
  • Conda: conda install -c conda-forge xmlsec

bcrypt

  • Requires C compiler and potentially Rust (cargo).
  • Debian/Ubuntu: sudo apt-get install build-essential cargo
  • Fedora/CentOS/RHEL: sudo yum install gcc cargo
  • Alpine: apk add gcc musl-dev cargo
  • Conda: conda install -c conda-forge bcrypt

hdbscan

  • Requires C compiler and Python development headers. Depends heavily on NumPy, SciPy, scikit-learn, Cython.
  • Best installed via conda: conda install -c conda-forge hdbscan
  • If using pip, ensure build tools (4.1, 4.2) and cython (pip install cython) are installed first.

PyNaCl

  • Requires C compiler and libsodium development library.
  • Debian/Ubuntu: sudo apt-get install build-essential libsodium-dev
  • Fedora/CentOS/RHEL: sudo yum install libsodium-devel
  • macOS: brew install libsodium
  • Conda: conda install -c conda-forge pynacl

onnx

  • Requires C++ compiler, Python dev headers, and Protobuf compiler/libraries.
  • Debian/Ubuntu: sudo apt-get install build-essential python3-dev libprotobuf-dev protobuf-compiler
  • Conda: conda install -c conda-forge numpy protobuf libprotobuf onnx is often the most reliable way.

spacy

  • Requires C compiler and Python development headers. Depends on many other packages like numpy, cython.
  • Ensure pip, setuptools, wheel are up-to-date.
  • Installation is usually pip install -U spacy followed by downloading models like python -m spacy download en_core_web_sm.
  • Conda: conda install -c conda-forge spacy

sip

  • Build tool often used by PyQt/PySide. Requires C++ compiler.
  • Usually best installed via pip install sip. If build fails, ensure C++ build tools (4.1) are installed.
  • Conda: conda install -c anaconda sip

scipy

  • Requires C, C++, and Fortran compilers, Python development headers, and BLAS/LAPACK libraries. Pre-built wheels are usually available.
  • Ensure pip is up-to-date. Install NumPy first (pip install numpy).
  • System Package Managers (Often Easiest for SciPy):
    • sudo apt-get install python3-scipy (Debian/Ubuntu)
    • sudo dnf install python3-scipy (Fedora)
    • brew install scipy (macOS)
  • Conda: conda install -c anaconda scipy

Conclusion

The error ERROR: Could not build wheels for X which use PEP 517... indicates a failure during the source build process, usually because pip couldn't find a pre-built wheel for your system.

The most common solutions are:

  1. Upgrade pip, setuptools, and wheel: This ensures compatibility with the PEP 517 build system.
  2. Install missing system-level build dependencies: This is the most frequent cause for packages involving compiled code. Consult the specific package's documentation for the required compilers (C/C++/Rust) and library development headers (-dev or -devel packages) for your operating system.
  3. Verify Python version compatibility.
  4. Use a virtual environment.

If general solutions fail, check the package-specific prerequisites listed above or in the package's documentation, and ensure they are installed correctly before retrying the pip install command. Using conda can often simplify dependency management for complex scientific packages.

Navigation