What do the -X gil switch and PYTHON_GIL do on a free-threaded CPython build?

## What these two controls actually are CPython 3.14 has two knobs for the global lock, and both are read once, at interpreter startup: - the command-line switch `-X gil=0` / `-X gil=1` - the environment variable `PYTHON_GIL=0` / `PYTHON_GIL=1` They do the same thing, the switch takes precedence when both are given, and — this is the part candidates get wrong — **neither creates a free-threaded interpreter**. They are only meaningful on a binary that was configured with `--disable-gil`, that is, the `t`-suffixed interpreter. On a default build, removing the lock is not something a flag can do: the lock is woven into how objects are allocated and reference-counted in that binary. So read them as: *given a free-threaded interpreter, which mode should this run use?* ## `gil=1` — put the lock back This is the more useful of the two in day-to-day work. It lets one installed binary answer the question "is this bug caused by losing the GIL?" without reinstalling anything. Run your suite normally, then run it with `PYTHON_GIL=1`, and compare. If a failure disappears under `gil=1`, you have a genuine data-sharing bug that the lock's coarse serialization used to hide, not a change in the language's semantics. It is also the escape hatch for a dependency that has not been made safe yet. You keep the free-threaded binary in your image, you keep the deployment shape, and you run serialized until the dependency catches up. What you do *not* keep is the performance benefit: you are paying the free-threaded build's single-threaded overhead — roughly 5–10% on 3.14 — while executing bytecode one thread at a time. It is a bridge, not a destination. ## `gil=0` — pin the lock off On a free-threaded build the lock is already off, so this looks redundant. It is not, because of one automatic behaviour: when the interpreter imports a C extension module that has not declared that it is safe without the lock, it **turns the GIL back on for the whole process** and emits a `RuntimeWarning` naming the module. `-X gil=0` suppresses that automatic re-enable and keeps running lock-free. That is a measurement tool and an experiment tool. Treat it as a load-bearing production setting only with your eyes open: you are overruling an extension author who has not claimed thread safety, and if they were right to stay silent, the failure mode is memory corruption in C, not a clean Python exception. The honest use is: pin it off in a benchmark to see what the extension is costing you, then either help upstream declare support or move that work out of the process. ## Reading the result back ```python import sys print(sys._xoptions.get("gil")) # '0', '1', or None if not passed print(sys._is_gil_enabled()) # the state that actually resulted ``` `sys._xoptions` tells you what was *requested* on the command line; `sys._is_gil_enabled()` tells you what you *got*. The environment variable does not show up in `sys._xoptions` at all, which is a good reason to prefer logging the second line rather than reconstructing intent from the first. In a container where the variable may be injected by an orchestration layer several files away from anything you wrote, the effective-state call is the only answer you can trust. ## Startup-only, and why that matters There is no supported way to flip the lock mid-process. The decision is made before your first line of Python runs, which means it belongs in your image, your process manager unit, or your entrypoint — not in application code. A common mistake is trying to set `PYTHON_GIL` inside the program with `os.environ` and expecting it to take effect; by then the interpreter has long since read it. One consequence worth stating for interviews: because the automatic re-enable happens during *import*, the value of `sys._is_gil_enabled()` can legitimately change between the top of your entry module and the end of your imports. Any check you write belongs after the import block, not before it.