How to Resolve Python "ERROR: Could not build wheels for X which use PEP 517"
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 (likesetup.py
orpyproject.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 withpip
. It allows packages to specify their build dependencies inpyproject.toml
.
The error "Could not build wheels..." means:
pip
couldn't find a pre-built wheel for the package compatible with your environment.- It fell back to building from the source distribution.
- The build process (using the PEP 517 interface) failed.
Common Causes
- Outdated Build Tools: An old version of
pip
,setuptools
, orwheel
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.
# Recommended command (ensures using pip for the right Python)
python -m pip install --upgrade pip setuptools wheel
# Alternative commands (use pip or pip3 as appropriate)
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"
orsudo 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
(orpython3.x-dev
for a specific version likepython3.10-dev
) - Fedora/CentOS/RHEL:
sudo yum install python3-devel
(orpython3.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
: Needslibxml2
,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
- 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...
). - Check Package Documentation: The installation section of the package's official documentation or PyPI page is the definitive source for prerequisites.
- Search Online: Search for "install <package-name> <your-operating-system> prerequisites" or "Could not build wheels for <package-name> <your-operating-system>".
After installing the required system dependencies, retry pip install <package-name>
.
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).
Solution 4: Use a Virtual Environment (Recommended)
Always use virtual environments to isolate project dependencies and avoid conflicts.
# Create
python3 -m venv venv
# Activate
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
# Upgrade core tools WITHIN the venv
pip install --upgrade pip setuptools wheel
# Install your package
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 oldersetup.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'spyproject.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 usednf
instead ofyum
) - macOS:
brew install openldap
(might require setting LDFLAGS/CPPFLAGS, checkpython-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 correctpython3.x-dev
if needed) - Fedora/CentOS/RHEL:
sudo yum install portaudio-devel python3-devel
- macOS:
brew install portaudio
then potentiallybrew 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
, thenpip install pycocotools
. - Windows: Often problematic. Try installing a Windows-specific fork:
pip install pycocotools-windows
- Conda:
conda install -c conda-forge pycocotools
orconda install -c esri pycocotools