Why does pip sometimes compile a package from source instead of installing a prebuilt wheel?

## Two different install paths pip has two ways to install a project. Given a wheel, it verifies the file's compatibility tags, unpacks the archive into the environment and writes the metadata — no code from the project runs, and no compiler is involved. Given a source distribution, it must *build* one: set up an isolated build environment, install the declared build backend and its requirements, and ask that backend to produce a wheel, which it then installs. When the project contains C, Rust or Fortran sources, that step invokes a compiler on your machine. So "pip started compiling" always means the same thing: **no candidate wheel's tags matched**, and pip fell back. ## What "matched" means The running interpreter defines an ordered set of acceptable tag triples — interpreter tag, ABI tag, platform tag. pip compares each available file's tags against that set. A miss on any one of the three disqualifies the file: - **Interpreter or ABI miss.** The project publishes `cp313` wheels and you have just moved to CPython 3.14. This is the single most common cause, and it appears in a wave every October when a new Python minor release lands and the compiled-extension ecosystem has not caught up. - **Platform miss.** You are on ARM64 and only x86-64 wheels exist; or you are on a musl-based image while the project publishes only glibc-baseline Linux wheels; or the wheels' libc baseline is newer than your host's. - **No wheels at all.** Some projects publish only an sdist, by choice or because they never set up a build matrix. A fourth, non-tag cause: you asked for it. `--no-binary=:all:` forces the source path, and installing from a directory, a VCS URL or a plain `.tar.gz` skips wheels by definition. ## Why it hurts A source build is slow — seconds for a pure-Python project, minutes for a large compiled one — and it is fragile in a way a wheel install is not, because it depends on the machine having a compiler, the right headers and enough memory. A container image or CI job that quietly worked because a wheel existed will break the day the wheel stops matching, and the error text will come from a compiler rather than from pip, which is why the cause is so often misdiagnosed. ## Diagnosing it Read the tags. `python -m pip debug --verbose` prints the compatible tag list for the interpreter you are running, most specific first. Then look at what the project actually publishes: if the newest files are `cp313-cp313-manylinux_2_28_x86_64` and you are on CPython 3.14, the mismatch is in the interpreter field. If they are `manylinux` and you are on a musl-based image, the mismatch is in the platform field. One comparison names the cause. ## Controlling it Make the behaviour a decision rather than an accident: - `pip install --only-binary=:all: <name>` fails immediately when no wheel matches, instead of compiling. In CI and in image builds this turns a ten-minute surprise into an instant, readable failure. - `pip install --no-binary=:all: <name>` forces the source path — occasionally wanted when you must build against local libraries or a specific instruction set. - `--prefer-binary` biases the resolver towards versions that have wheels, which sometimes means picking a slightly older release that does have one. - Pin the interpreter version your project's dependencies actually ship binaries for, rather than tracking the newest release on day one. ## Reading the failure correctly The error text misleads people, because it comes from the wrong layer. A missing header, an unknown compiler flag or a linker error are all *symptoms* of the fallback, not the cause; nothing is wrong with your compiler setup, and installing build tools to make the message go away treats a packaging problem as a toolchain problem. The question to ask first is always "why was there no wheel for me", and the answer is one of the three tag fields or an index that publishes no wheels at all. ## The cache When pip does build a source distribution, it stores the resulting wheel in its local cache and reuses it for later installs of the same project, version and tag set on that machine. That is why the compile appears to happen only once locally, and why it appears *every* time in a fresh container: the cache is not in the image unless you deliberately mount or preserve it. The correct fix is rarely to warm the cache; it is to install an interpreter and base image for which the wheels you need actually exist, or to build the wheel once yourself and install that artefact everywhere.