What does the ABI tag cp314t on a wheel mean, and why won't a cp314 wheel work there?

## Two builds of one version The free-threaded interpreter is CPython with the global interpreter lock compiled out. It first shipped as an experimental build in 3.13 and became an officially supported build in 3.14, with a documented single-threaded cost of roughly five to ten percent. Crucially, it is a **build**, chosen when the interpreter is compiled and installed, not a flag you pass to an ordinary interpreter. On a machine with both installed you have two interpreters of the same Python version, each with its own environment and its own installed packages. Removing the lock changes internals that compiled extensions depend on: reference counting, object layout, and the guarantees around what may touch an object concurrently. So the binary interface differs, and any extension module must be compiled specifically for the free-threaded build. ## How the tag encodes it The distinction lives in the ABI field of the wheel filename, as a trailing `t`: ``` pkg-1.0-cp314-cp314-manylinux_2_28_x86_64.whl # standard build pkg-1.0-cp314-cp314t-manylinux_2_28_x86_64.whl # free-threaded build ``` The same marker appears in the extension-module filenames the build produces, which is a quick way to confirm which interpreter an installed extension belongs to: `sysconfig.get_config_var("EXT_SUFFIX")` reports something ending in `.cpython-314-...` on the standard build and `.cpython-314t-...` on the free-threaded one. Because the tag sets are disjoint for compiled artefacts, the free-threaded interpreter's accepted tag list simply does not contain `cp314`, and a `cp314` wheel is not a candidate for it. There is no compatibility shim and no runtime translation: the file is skipped, and installation falls back to the source distribution — which means a compiler, and a project whose sources are actually ready for a lock-free interpreter. ## What is unaffected Pure-Python distributions do not care. A `py3-none-any` wheel carries no ABI constraint and installs identically on both builds, which is why the great majority of the index works on the free-threaded interpreter on day one. The friction is concentrated in the compiled minority, and it is exactly the layer that also has to be *correct* without the lock, not merely compiled: an extension built for a free-threaded interpreter must be safe under genuine parallel execution of Python-level code, which the lock previously masked. ## Operating consequences Three practical points follow. First, **environments do not transfer.** An environment built for the standard interpreter cannot be pointed at the free-threaded one, because its compiled artefacts are wrong. Each build gets its own environment, and your image or lockfile tooling must know which one it targets. Second, **coverage is a real constraint on adoption.** Before moving a workload, take the dependency set's compiled members and check whether each publishes a `t`-tagged wheel for your platform. Where one does not, the choices are the familiar ones: build it yourself, pin a version that works, drop the dependency, or wait. Installing with `--only-binary=:all:` on the free-threaded interpreter turns "missing coverage" into an immediate list rather than a slow discovery. Third, **the payoff is not automatic.** Removing the lock lets Python-level threads run in parallel, which helps CPU-bound Python code; it does nothing for a workload already dominated by a compiled routine that released the lock anyway, and the single-threaded penalty applies regardless. The tag is a compatibility question; whether the build is worth adopting is a performance question, and answering the first tells you nothing about the second. ## How this differs from other tag misses Most tag mismatches are about *where* the code runs: a different architecture, a different C library baseline, a different operating system. This one is about *which interpreter binary* it runs in, on one machine, for one Python version. That makes it easy to misread: the version numbers agree, the platform agrees, the wheel is right there in the index, and the install still compiles. Reading the ABI field as a build identity is what resolves it, and it is also why the fix is never "upgrade the installer" but always "find or build a t-tagged artefact". ## The interview point What a candidate should show is that they read the ABI field as a *build identity*, not as a version number. `cp314` and `cp314t` are the same Python version, the same source language and two incompatible binaries; the packaging system's job is to keep you from ever installing the wrong one, and a trailing letter is how it does it. Knowing that is what turns "this suddenly compiles on the free-threaded interpreter" into an expected, explainable result rather than a mystery.