Fix: ERROR: Could not build wheels / Failed building wheel (pip)

The Error

You run pip install and get one of these:

ERROR: Could not build wheels for numpy, which is required to install pyproject.toml-based projects

Failed building wheel for cryptography

error: subprocess-exited-with-error

× Building wheel for PyYAML (pyproject.toml) did not run successfully.
│ exit code: 1
╰─> [25 lines of output]
    ...
    error: command 'gcc' failed: No such file or directory

ERROR: No matching distribution found for tensorflow==2.15.0

These errors all point to the same core problem: pip can’t install a package because it can’t build it from source, can’t find a pre-built binary (wheel) for your platform, or the package doesn’t support your Python version.

Why This Happens

Most Python packages on PyPI are distributed as wheels—pre-built binary packages that install instantly without compilation. But wheels are platform-specific. A wheel built for Linux on x86_64 won’t work on macOS on Apple Silicon.

When pip can’t find a compatible wheel, it falls back to building the package from source. This requires:

• A C/C++ compiler (gcc, clang, or MSVC)
• Python development headers (python3-dev / python3-devel)
• System libraries the package depends on (libffi, libssl, libxml2, etc.)
• Build tools (make, cmake, pkg-config)

If any of these are missing, the build fails. The error messages are often long and buried in compiler output, but the root cause is almost always one of the above.

“No matching distribution found” is different. It means pip can’t find any version of the package (source or wheel) that matches your Python version, OS, or architecture. This typically happens when:

• The package doesn’t support your Python version (e.g., Python 3.13 when the package only supports up to 3.12)
• The package doesn’t have builds for your platform (e.g., ARM64 / Apple Silicon)
• You misspelled the package name
• The package has been removed from PyPI

Fix 1: Install Build Tools and a C Compiler

The most common cause. You’re missing the compiler and development tools needed to build C extensions.

Linux (Debian/Ubuntu)

sudo apt update
sudo apt install build-essential python3-dev

build-essential installs gcc, g++, make, and other essential build tools. python3-dev installs the Python header files needed to compile C extensions.

For a specific Python version:

sudo apt install python3.12-dev

Linux (Fedora/RHEL/CentOS)

sudo dnf groupinstall "Development Tools"
sudo dnf install python3-devel

Linux (Arch)

sudo pacman -S base-devel python

Arch ships Python headers with the main python package.

macOS

Install Xcode Command Line Tools:

xcode-select --install

This gives you clang, make, and the standard C headers. You don’t need the full Xcode IDE—the command line tools are sufficient.

If you already have them installed but still get errors after a macOS upgrade, reinstall:

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Windows

Install Microsoft Visual Studio Build Tools:

1. Download from https://visualstudio.microsoft.com/visual-cpp-build-tools/
2. Run the installer
3. Select “Desktop development with C++”
4. Install and restart your terminal

Without these build tools, any package with C extensions will fail on Windows. The error usually looks like:

error: Microsoft Visual C++ 14.0 or greater is required.

Fix 2: Install Missing System Libraries

Some packages need specific system libraries. The error output usually tells you which one is missing, but it’s buried in the compiler output. Look for lines like fatal error: ffi.h: No such file or directory or Package libssl was not found.

Common packages and their system dependencies

cryptography:

# Debian/Ubuntu
sudo apt install build-essential libssl-dev libffi-dev python3-dev

# Fedora
sudo dnf install openssl-devel libffi-devel python3-devel

# macOS
brew install openssl libffi
export LDFLAGS="-L$(brew --prefix openssl)/lib"
export CPPFLAGS="-I$(brew --prefix openssl)/include"

lxml:

# Debian/Ubuntu
sudo apt install libxml2-dev libxslt1-dev python3-dev

# Fedora
sudo dnf install libxml2-devel libxslt-devel python3-devel

# macOS
brew install libxml2 libxslt

Pillow:

# Debian/Ubuntu
sudo apt install libjpeg-dev zlib1g-dev libfreetype-dev liblcms2-dev libwebp-dev

# Fedora
sudo dnf install libjpeg-devel zlib-devel freetype-devel lcms2-devel libwebp-devel

# macOS
brew install libjpeg zlib freetype

psycopg2:

# Debian/Ubuntu
sudo apt install libpq-dev python3-dev

# Fedora
sudo dnf install postgresql-devel python3-devel

# macOS
brew install postgresql

Tip: if a package has a pure-Python or pre-built alternative, use that instead. For example, psycopg2-binary ships pre-built wheels and doesn’t require libpq-dev:

pip install psycopg2-binary

mysqlclient:

# Debian/Ubuntu
sudo apt install default-libmysqlclient-dev build-essential python3-dev pkg-config

# Fedora
sudo dnf install mysql-devel python3-devel

# macOS
brew install mysql pkg-config

Fix 3: Upgrade pip, setuptools, and wheel

An outdated pip may not find wheels that exist on PyPI. Newer pip versions support more wheel formats (including newer manylinux tags) and handle build dependencies better.

python -m pip install --upgrade pip setuptools wheel

Then retry your install:

pip install <package>

This is especially important on older systems where the default pip might be years old. A pip from 2021 won’t know about manylinux_2_28 wheels published in 2024.

Fix 4: Use Pre-built Wheels (—prefer-binary)

Force pip to prefer pre-built wheels over source distributions:

pip install --prefer-binary <package>

This tells pip to choose a wheel even if a newer source distribution is available. Useful when a package has wheels for most versions but the very latest release only has a source dist.

You can also force pip to only install from wheels and never attempt a source build:

pip install --only-binary :all: <package>

If no compatible wheel exists, this will fail with an error instead of attempting a doomed build.

Fix 5: Check Python Version Compatibility

The package may not support your Python version. This is the most common cause of “No matching distribution found.”

Check your Python version:

python --version

Then check what Python versions the package supports. Go to the package’s PyPI page (e.g., https://pypi.org/project/<package>/) and look at the “Requires Python” field and the available download files.

You can also check from the command line:

pip install <package>==

This intentionally errors but shows all available versions. Pick a version that supports your Python.

If you’re on Python 3.13 and the package only supports up to 3.12, you have two options:

1. Wait for the package to release a new version with 3.13 support
2. Use an older Python version that the package supports

For managing multiple Python versions, use pyenv (Linux/macOS) or download specific versions from python.org (Windows).

Fix 6: Platform-Specific Wheels (Apple Silicon / ARM64)

If you’re on Apple Silicon (M1/M2/M3/M4) or ARM64 Linux, some packages don’t have pre-built wheels for your architecture.

Apple Silicon (macOS ARM64)

Older packages may only ship x86_64 wheels. Options:

Install Rosetta 2 and use an x86_64 Python:

softwareupdate --install-rosetta

Then install the x86_64 version of Python from python.org (the “macOS 64-bit universal2 installer” supports both architectures).

Use Conda/Miniforge: Miniforge provides ARM64-native builds for most scientific Python packages:

# Install Miniforge (ARM64-native)
brew install miniforge
conda create -n myenv python=3.12
conda activate myenv
conda install numpy pandas scipy

ARM64 Linux (Raspberry Pi, AWS Graviton)

Many packages now have aarch64 wheels, but some still don’t. Install build dependencies and build from source:

sudo apt install build-essential python3-dev gfortran libopenblas-dev
pip install numpy

For scientific packages, Conda (via Miniforge) often has ARM64 builds before PyPI wheels are available.

Fix 7: Fix Cython / setuptools Version Issues

Some packages require specific versions of Cython or setuptools to build. If you see errors like Cython.Compiler.Errors.CompileError or setuptools.extern.packaging.version.InvalidVersion, try:

pip install --upgrade Cython setuptools

Some older packages break with newer setuptools. If upgrading doesn’t help, try pinning an older version:

pip install "setuptools<71"
pip install <package>

This is common with packages that haven’t updated their build configuration for newer setuptools versions, particularly after setuptools 71.0 removed deprecated features.

Fix 8: Use a Virtual Environment

If you’re installing into the system Python, you might have permission issues or conflicting versions that interfere with the build. A virtual environment gives you a clean slate.

python -m venv .venv
source .venv/bin/activate    # Linux/macOS
# .venv\Scripts\activate     # Windows

pip install --upgrade pip setuptools wheel
pip install <package>

This also avoids the externally-managed-environment error on modern Linux distributions.

Still Not Working?

Read the actual error

The pip output is verbose, but the real error is usually near the end. Scroll up past the “ERROR: Could not build wheels” line and look for:

• fatal error: *.h: No such file or directory — missing header file. Install the corresponding -dev / -devel package.
• command 'gcc' failed — no C compiler installed.
• pkg-config errors — install pkg-config and the library it’s looking for.
• LINK : fatal error LNK* — Windows linker error. Reinstall Visual Studio Build Tools.
• RuntimeError: CMake must be installed — install cmake: pip install cmake or use your system package manager.

Install cmake or meson

Some packages (like dlib, llvmlite) need cmake or meson to build:

pip install cmake meson-python meson
# Then retry
pip install <package>

Use Conda instead of pip

For scientific and data packages (NumPy, SciPy, TensorFlow, PyTorch, OpenCV), Conda often works when pip doesn’t. Conda ships its own pre-compiled binaries with all dependencies bundled, so you don’t need system libraries.

conda install numpy scipy pandas scikit-learn

Check for a binary variant of the package

Some hard-to-build packages offer a pre-built variant:

The package is not on PyPI

“No matching distribution found” can also mean the package name is wrong or it’s hosted elsewhere. Check:

# Verify the package name
pip search <package>  # deprecated, use the PyPI website instead
pip install <package> --dry-run

Some packages are hosted on custom indexes. Check the project’s documentation for install instructions:

# Example: installing PyTorch from its own index
pip install torch --index-url https://download.pytorch.org/whl/cpu

Build isolation is interfering

pip builds packages in an isolated environment by default (PEP 517). Sometimes this causes issues if the package’s build dependencies have conflicts. Try disabling build isolation:

pip install --no-build-isolation <package>

You’ll need to manually install the package’s build dependencies first (check pyproject.toml for [build-system] requires).

You’re behind a proxy or firewall

If pip can’t download build dependencies, the build will fail. Configure pip to use your proxy:

pip install --proxy http://user:password@proxy.example.com:8080 <package>

Or set the environment variable:

export HTTPS_PROXY=http://proxy.example.com:8080
pip install <package>

Rust compiler required

Some packages (like cryptography >= 3.4 and tokenizers) require a Rust compiler. If you see error: can't find Rust compiler:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
pip install <package>

On Windows, download and run the Rust installer from https://rustup.rs.

Related: Fix: ModuleNotFoundError: No module named | Fix: error: externally-managed-environment | Fix: IndentationError: unexpected indent