Python Package Won't Install? Check Your Python Version

When pip install fails with "No matching distribution found" or "Failed building wheel", check your Python version before anything else. Your Python is either too old for the package's current release, or too new for it to have published a ready-made wheel yet. Confirm which Python pip is using, check whether a wheel exists for it, and pin a supported version for the project.

This problem returns every October. Python 3.15.0 was released on October 9, 2026, and in the weeks that followed, people who installed the newest Python found that common data packages would not install. At the other end, Python 3.10 reached end of life in October 2026, and current numpy releases no longer support 3.11. The commands below were run on November 7, 2026 on macOS with pip 26.0.1, uv 0.11.2, and Python 3.11.15, 3.13.12, and 3.14.3. Wheel availability changes almost daily, so treat the specific package results as a snapshot and rerun the checks yourself.

Recognize a Python-version problem

These messages usually mean the package and your interpreter do not match, not that the package is broken:

A wheel is a prebuilt package file. Its file name records which Python versions and operating systems it supports, for example numpy-2.4.6-cp311-cp311-macosx_14_0_arm64.whl is for CPython 3.11 on Apple silicon. Packages with compiled code need a separate wheel for each Python version, unless they use the stable ABI and are tagged abi3. When no matching wheel exists, pip falls back to building from source, which needs compilers and sometimes system libraries or a Rust toolchain.

Confirm which Python pip is using

Many "wrong version" problems are really "wrong interpreter" problems. Ask the interpreter you intend to use, and run pip through it:

python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip --version

The second command prints the pip version and, at the end, the Python it belongs to, such as (python 3.11). If that is not the interpreter you expected, fix the environment first; the PATH guide and the Jupyter import guide walk through interpreter mismatches. Always install with python -m pip rather than a bare pip so that the package goes to the interpreter you just checked.

Case 1: your Python is too old

numpy 2.5 requires Python 3.12 or newer. In a Python 3.11.15 environment, asking for it exactly fails:

python -m pip install "numpy==2.5.4"

The output starts with a long line of skipped releases. The relevant part, reformatted onto separate lines, is:

ERROR: Ignored the following versions that require a different python version: ...
 2.5.0 Requires-Python >=3.12
 2.5.1 Requires-Python >=3.12
 ...
 2.5.4 Requires-Python >=3.12
ERROR: No matching distribution found for numpy==2.5.4

Read the Requires-Python range: this is not a network problem or a typo. Without a pin, the same environment does not fail at all; python -m pip install numpy --dry-run reported Would install numpy-2.4.6. That silent fallback is usually fine, but it explains why a tutorial or a teammate's code can use a feature your environment does not have.

You have two honest fixes: install the latest release that supports your Python, or move the project to a newer Python. Do not use --ignore-requires-python to force it; the package declared the range because it does not work outside it.

Case 2: your Python is too new

A new Python release changes the binary interface that compiled extensions use, so packages with compiled code have to publish new wheels after each release. Large projects often publish them around release day; others take weeks. Until then, pip tries to build from source, and on a typical analyst laptop that build often fails with a long compiler error.

A month after Python 3.15.0, the picture was mixed. This snapshot was taken on November 7, 2026 by asking pip for wheel-only downloads for CPython 3.15:

The pyarrow 3.15 wheels were uploaded on November 3, 2026, almost four weeks after Python 3.15.0. Anyone who upgraded on release day and needed pyarrow, which pandas uses for Parquet files, hit a build failure until then. PyYAML is a dependency of many tools, so its missing 3.15 wheel can surface while installing something that never mentions YAML.

Check for a wheel before you install

To ask whether a package has a wheel for the interpreter you are using, download it without building anything:

python -m pip download pyarrow --only-binary=:all: --no-deps -d wheel-check

If a wheel exists, the file appears in wheel-check, and its name shows the tags it matched. If not, pip says No matching distribution found immediately, instead of starting a compile. Delete the folder afterward.

To check a Python you have not installed yet, tell pip which version and platform to target. pip accepts these target options only for a check that cannot install anything, so keep --only-binary=:all: and --no-deps in the command:

python -m pip download "pyyaml==6.0.3" --only-binary=:all: --no-deps -d wheel-check \
  --python-version 3.15 --implementation cp --platform macosx_15_0_arm64

That command returned No matching distribution found for pyyaml==6.0.3. Choose the platform tag carefully. With macosx_11_0_arm64, scikit-learn, xgboost, and numba all looked missing, because their Apple silicon wheels are tagged for macOS 12 or later; with macosx_15_0_arm64, all three were found. Use a tag for your actual macOS version, win_amd64 for 64-bit Windows, or a Linux tag such as manylinux_2_28_x86_64. The package's Download files page on PyPI shows the same information in the file names.

The same flag protects a real install. python -m pip install --only-binary=:all: -r requirements.txt refuses to compile anything, so a missing wheel produces a short, clear error instead of a page of compiler output. Remove the flag only for packages you know how to build.

Pin a supported Python for each project

Choose the newest Python that every dependency has wheels for, and record that choice in the project so the next environment you build uses it too. For analysis work, that is often one version behind the newest for the first weeks or months after an October release.

With the standard library

Create the environment with an explicit interpreter instead of whatever python3 happens to mean on that machine:

python3.13 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

On Windows, the Python launcher selects the version: py -3.13 -m venv .venv, then .venv\Scripts\python.exe -m pip install -r requirements.txt. Write the chosen version at the top of your README or requirements file, since venv itself does not record it for the next person.

With uv

uv can record the version in a .python-version file, which uv venv and uv run then follow:

uv python pin 3.13
uv venv
uv pip install "pandas==3.1.1"

In the test, uv venv reported Using CPython 3.13.12, and pandas 3.1.1 imported under Python 3.13.12.

Do not rely on requires-python alone. A project created with uv init --bare --python 3.13 got requires-python = ">=3.13" in pyproject.toml, but no .python-version file. The first uv add then built the environment with Python 3.14.3, the newest interpreter on the machine, because >=3.13 allows it. After uv python pin 3.13, the next uv run rebuilt the environment with 3.13.12. requires-python is a minimum; .python-version is the pin. Commit both files.

With conda

Name the version when you create the environment, for example conda create -n analysis python=3.13 pandas. Conda packages are built separately from PyPI wheels, so check the conda channel you use rather than assuming PyPI availability. These conda commands were not run for this guide.

If you must use the newest Python

• Check the dependency, not just the package you typed. Run the install with --only-binary=:all:; the error names the package without a wheel, which may be several levels down the dependency tree.
• Look for a newer release. Wheels often arrive in a patch release. Upgrading the dependency can fix it, and an exact pin in your requirements can be what is holding you back.
• Build only when you can. Compiling from source requires the toolchain the project documents, such as Xcode Command Line Tools on macOS, Microsoft C++ Build Tools on Windows, or Rust for some packages. If you are not prepared to maintain that, wait for wheels.
• Keep a second environment. It costs nothing to keep one environment on the new Python for experiments and one on the supported Python for reports people depend on.

Moving to a new major version of a package at the same time as a new Python makes failures hard to attribute. Change one thing, then check your results; the pandas 3 upgrade guide shows how to compare outputs across two environments.

FAQ

Why does the same requirements file install on my colleague's machine but not mine?

Wheels are specific to Python version, operating system, and processor architecture. A colleague on Windows with Python 3.13 may get a wheel while your Mac with Python 3.15 has to build from source. Compare python -m pip --version on both machines and pin the Python version in the project.

Should I always use the newest Python?

Not for work other people depend on. Newer Python versions bring real improvements, but analysis projects depend on many compiled packages. Move when your whole dependency list has wheels for the new version, and test the upgrade in a separate environment first.

Is --ignore-requires-python a safe workaround?

No. It tells pip to install a release that its maintainers declared incompatible with your interpreter. The install may succeed and then fail at import time, or behave incorrectly. Use a supported version of the package or of Python instead.