Documentation on level of support for the free-threaded build

[ngoldbaum]

Right now, uv's solver considers the free-threaded build experimental and won't use it unless you explicitly specify a free-threaded interpreter with e.g. --python. This leads to some surprising behaviors. Some of these are marked as bugs in uv and will likely be fixed but some of them seem to be the expected behavior of uv considering free-threading experimental:

• uv run discards free-threaded (3.13t) environments and recreates non-free-threaded ones #15739
• uv incorrectly thinks a 3.13t venv doesn't satisfy >=3.8 #12445
• uv cannot find its own free-threaded Python when installing tools #8480

This came up in the context of the cryptography CI configuration where I'm trying to add support for the free-threaded build:

• Free threaded support pyca/cryptography#12555 (comment)

It'd be nice to have this level of support explicitly documented somewhere.

It'd also be nice if the uv developers could think about what is needed for the free-threaded build to no longer be considered experimental and write that down somewhere.

[ngoldbaum]

The first cryptography release to support the free-threaded build hit some snags due to fallout from this: pyca/cryptography#13447

I guess I already knew about this issue when I updated the CI configuration for 3.14 so more docs wouldn't help, but I guess it shows that it leads to some surprising behaviors.

[zanieb]

It's on my todo list to look into this.

[zanieb]

I'm not sure if a 3.13 free-threaded environment should be used without opt-in, as free-threading was considered experimental there. We could consider changing that for 3.14+?

[ngoldbaum]

I think changing it for 3.14+ makes sense and would be very helpful! That would jibe with cibuildwheel's decision to build 3.14t wheels by default starting in version 3.1.

3.14t is not only less buggy than 3.13t but also it's 30% faster so I suspect most people will switch very quickly.

[rgommers]

It makes sense to me too to change this for >=3.14. Still give it lowest priority, but if it's the only interpreter available then use it. That will make using free-threaded interpreters in CI in particular much easier, since that's often where you only have a single interpreter available, and having to force it with something like --python='${{ steps.setup-python.outputs.python-path }}' is very ugly.

Even on user machines I don't think there's a problem, since (a) it'll be very rare for there to be no other interpreter installed at all, and (b) if it really is the only one, then good chance that the user actually wants to be using it.