pip install numpy: error metadata-generation-failed (tested)

Q: Why does pip install numpy fail with metadata-generation-failed?

pip found no wheel for your Python version (typically an old pinned numpy such as 1.26.4 on a newer Python), downloaded the .tar.gz source and the build failed, e.g. Unknown compiler(s) when no C compiler is installed.

Q: How do I see which numpy versions have a wheel for my Python?

Run pip install --only-binary=:all: numpy== . The error lists every version available as a wheel for your Python and platform after "from versions:".

error: metadata-generation-failed when installing numpy means pip found no pre-built wheel for your Python version and tried to compile numpy from source, which failed (here: Unknown compiler(s)). Usually an old pinned numpy on a newer Python. Unpin or upgrade numpy, or use a Python version that numpy release has wheels for.

1. Reproduce it: an old pinned numpy on a new Python

The official python:3-slim Docker image (Python 3.15.1, no C compiler installed), running docker run --rm -v $PWD:/w python:3-slim sh /w/run.sh with this run.sh:

python -V
echo '$ pip install numpy==1.26.4'
pip install --no-cache-dir --disable-pip-version-check --root-user-action=ignore numpy==1.26.4 2>&1 | tail -40
echo "exit=$?"

Output (only the last 40 lines of pip's output kept by tail):

Python 3.15.1
$ pip install numpy==1.26.4
  Getting requirements to build wheel: finished with status 'done'
  Installing backend dependencies: started
  Installing backend dependencies: finished with status 'done'
  Preparing metadata (pyproject.toml): started
  Preparing metadata (pyproject.toml): finished with status 'error'
  error: subprocess-exited-with-error
  
  × Preparing metadata (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [20 lines of output]
      + /usr/local/bin/python3.15 /tmp/pip-install-a20lxdsi/numpy_91bd3bf4ea0d4ee38e0c5581735403d6/vendored-meson/meson/meson.py setup /tmp/pip-install-a20lxdsi/numpy_91bd3bf4ea0d4ee38e0c5581735403d6 /tmp/pip-install-a20lxdsi/numpy_91bd3bf4ea0d4ee38e0c5581735403d6/.mesonpy-ipd3vb6l -Dbuildtype=release -Db_ndebug=if-release -Db_vscrt=md --native-file=/tmp/pip-install-a20lxdsi/numpy_91bd3bf4ea0d4ee38e0c5581735403d6/.mesonpy-ipd3vb6l/meson-python-native-file.ini
      The Meson build system
      Version: 1.2.99
      Source dir: /tmp/pip-install-a20lxdsi/numpy_91bd3bf4ea0d4ee38e0c5581735403d6
      Build dir: /tmp/pip-install-a20lxdsi/numpy_91bd3bf4ea0d4ee38e0c5581735403d6/.mesonpy-ipd3vb6l
      Build type: native build
      Project name: NumPy
      Project version: 1.26.4
      
      ../meson.build:1:0: ERROR: Unknown compiler(s): [['cc'], ['gcc'], ['clang'], ['nvc'], ['pgcc'], ['icc'], ['icx']]
      The following exception(s) were encountered:
      Running `cc --version` gave "[Errno 2] No such file or directory: 'cc'"
      Running `gcc --version` gave "[Errno 2] No such file or directory: 'gcc'"
      Running `clang --version` gave "[Errno 2] No such file or directory: 'clang'"
      Running `nvc --version` gave "[Errno 2] No such file or directory: 'nvc'"
      Running `pgcc --version` gave "[Errno 2] No such file or directory: 'pgcc'"
      Running `icc --version` gave "[Errno 2] No such file or directory: 'icc'"
      Running `icx --version` gave "[Errno 2] No such file or directory: 'icx'"
      
      A full log can be found at /tmp/pip-install-a20lxdsi/numpy_91bd3bf4ea0d4ee38e0c5581735403d6/.mesonpy-ipd3vb6l/meson-logs/meson-log.txt
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> numpy

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.
exit=0

Read it from the bottom up. metadata-generation-failed only says that pip tried to build numpy from source and the build's first step failed. The real reason is inside the [20 lines of output] box: ERROR: Unknown compiler(s). pip downloaded the source archive because numpy 1.26.4 has no pre-built wheel for this Python version, and building numpy needs a C compiler (and more).

The usual trigger is a pinned old numpy in requirements.txt (often numpy==1.2x, or something that requires numpy<2) on a Python release newer than that numpy.

2. Which numpy versions have a wheel for your Python

A second fresh container, same image:

P="pip install --no-cache-dir --disable-pip-version-check --root-user-action=ignore"
echo '$ pip install --only-binary=:all: numpy==1.26.4'
$P --only-binary=:all: numpy==1.26.4 2>&1 | tail -3
echo
echo '$ pip install "numpy<2"'
$P "numpy<2" 2>&1 | grep -E "Downloading|metadata-generation|Unknown compiler" | head -3
echo
echo '$ pip install numpy'
$P numpy 2>&1 | grep -E "Downloading|Successfully"
python -c "import numpy; print('numpy', numpy.__version__)"

Output:

$ pip install --only-binary=:all: numpy==1.26.4
ERROR: Could not find a version that satisfies the requirement numpy==1.26.4 (from versions: 2.5.2, 2.5.3, 2.5.4)
ERROR: No matching distribution found for numpy==1.26.4

$ pip install "numpy<2"
  Downloading numpy-1.26.4.tar.gz (15.8 MB)
      ../meson.build:1:0: ERROR: Unknown compiler(s): [['cc'], ['gcc'], ['clang'], ['nvc'], ['pgcc'], ['icc'], ['icx']]
error: metadata-generation-failed

$ pip install numpy
  Downloading numpy-2.5.4-cp315-cp315-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.metadata (6.6 kB)
Downloading numpy-2.5.4-cp315-cp315-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (16.7 MB)
Successfully installed numpy-2.5.4
numpy 2.5.4

--only-binary=:all: forbids source builds, so pip prints the honest error instead: the list after from versions: is every numpy release that has a wheel for your Python and platform. Here that was only 2.5.2 to 2.5.4.
"numpy<2" picks 1.26.4, downloads numpy-1.26.4.tar.gz (a source archive, not a .whl) and fails the same way. A .tar.gz download line is the early warning.
Unpinned pip install numpy downloaded a cp315 wheel and installed in seconds. If your code works with a current numpy, loosen the pin; see numpy 2 breaking changes for what changed in 2.0.

3. If you really need the old numpy: use an older Python

Installing gcc, gfortran and BLAS so numpy 1.26 compiles is possible, but it is slow and an old numpy may simply not support the new Python's C API. Using a Python version that the old numpy shipped wheels for is faster. With uv (on the Linux host, Python 3.11 downloaded by uv):

$ uv venv -p 3.11 v311 && uv pip install -p v311/bin/python numpy==1.26.4
Using Python 3.11.17 environment at: v311
Downloading numpy (17.4MiB)
 Downloaded numpy
 + numpy==1.26.4
3.11.17 numpy 1.26.4 1

Python 3.11 got a pre-built numpy 1.26.4 wheel; nothing was compiled. In Docker, the same idea is FROM python:3.11-slim instead of python:3-slim.

The same metadata-generation-failed error appears for any package with C extensions (pandas, scipy, lxml, ...) when no wheel matches; the fix is the same: check --only-binary=:all:, loosen the pin, or use an older Python. Related: numpy.dtype size changed · pip install failed · pip error: externally-managed-environment.

Frequently asked questions

Why does pip install numpy fail with metadata-generation-failed?

pip found no wheel for your Python version (typically an old pinned numpy such as 1.26.4 on a newer Python), downloaded the .tar.gz source and the build failed, e.g. Unknown compiler(s) when no C compiler is installed.

How do I see which numpy versions have a wheel for my Python?

Run pip install --only-binary=:all: numpy==<your pin>. The error lists every version available as a wheel for your Python and platform after "from versions:".

How do I fix it?

Remove or loosen the numpy pin so pip picks a release with a wheel, or create the environment with an older Python (e.g. uv venv -p 3.11) that the pinned numpy shipped wheels for.

Written with AI assistance. Measured on 2026-10-23 in fresh python:3-slim containers (Python 3.15.1, pip default for that image) and with uv 0.13.5 + CPython 3.11.17 on Linux. Each script was run verbatim and the output pasted unedited (pip download progress lines filtered as shown by grep/tail, plus uv's hardlink notice). PlainTables is our extension; numpy, pip and uv are free.