The Free-Threaded Build

## The symptom A flight-schedule differ fans a 340-case regression pack across a thread pool. It was moved to the free-threaded 3.14 interpreter specifically to get real parallelism on those CPU-bound comparisons, and the wall-clock time barely moved. Someone finally logs `sys._is_gil_enabled()` at startup and it prints `True` — on `python3.14t`. This is the single most important operational fact about the free-threaded build, because it fails *quietly*. Nothing crashes. Throughput just looks like the old interpreter, minus a few percent. ## Cause one: somebody asked for it `-X gil=1` or `PYTHON_GIL=1` runs the free-threaded binary with the lock on. That is a legitimate setting — it is how you bisect a suspected sharing bug — but it is also exactly the kind of thing that gets set once in a base image or a CI environment file and then inherited by a service that never wanted it. Check it first because it is cheap: `sys._xoptions.get("gil")` shows the command-line request, and the environment variable is one lookup away. Note that the variable does not appear in `sys._xoptions`, so a process can be running with the lock on and show nothing there — which is why the effective-state call, not the requested-option lookup, is what belongs in your startup log. ## Cause two: an extension asked for it A C extension module has to explicitly declare, at module initialization, that it is safe to run without the lock. If one that has not is imported, CPython **re-enables the GIL for the entire process** and emits a `RuntimeWarning` naming the module. One undeclared extension anywhere in your dependency graph — including a transitive one you never imported directly — serializes everything. To find it, make the warning impossible to miss and bisect the import block: ```python import sys, warnings warnings.simplefilter("always", RuntimeWarning) print("before:", sys._is_gil_enabled()) import my_package.pipeline print("after :", sys._is_gil_enabled()) ``` Because the flip happens during import, ordering matters: a check placed above the import block will happily report `False` while the process ends up serialized. Any assertion you write belongs *after* all imports, in the entrypoint. ## Why this is the worst of both worlds On 3.14 the free-threaded build costs roughly 5–10% on single-threaded work compared with the default build — the price of the new object and reference-counting machinery. That is a fine trade when threads genuinely run in parallel. When the lock is back on, you keep the tax and lose the benefit. You are strictly worse off than on the default interpreter, and no test fails to tell you. ## Fixing it, in order of preference 1. **Upgrade the dependency.** Many maintainers have shipped free-threading-capable builds since 3.14 made the build officially supported; a `cp314t` wheel exists precisely to carry them. 2. **Replace the offender.** A pure-Python equivalent, or a stdlib mechanism, removes the constraint entirely. On a differ that is mostly comparison logic, the C dependency is often peripheral — serialization or a date library — rather than the hot path. 3. **Move the work out.** If the extension is essential and unsafe, put it behind a process boundary and keep the free-threaded interpreter for the code that benefits. 4. **Pin it off with `-X gil=0`** only as a measurement, or as a considered risk with a named owner. You are overruling an author who never claimed thread safety, and the failure mode is memory corruption in C, not a Python traceback. There is also a fifth answer that interviewers like to hear you reach for honestly: **go back to the default build**. If the dependency cannot move, the free-threaded interpreter is buying you nothing and costing you a few percent plus a second supply chain. ## The guardrail The durable fix is not a diagnosis, it is a check. Assert the mode you deployed for, after imports, at startup, and fail loudly: ```python if not sys._is_gil_enabled(): log.info("running lock-free") else: raise SystemExit("deployed for free-threading but the GIL is on") ``` The ordering assumption baked into a slow rollout is that the binary you installed is the mode you are running. On this build that assumption is false often enough to be worth one line of startup code. Pair it with a benchmark that actually scales with thread count, so a regression that silently re-serializes the process shows up as a failed check rather than as a quarterly capacity surprise.