GeezerVison

# Standard Python (unchanged)
Pythonx.uv_init("""
[project]
name = "project"
version = "0.0.0"
requires-python = "==3.14.*"
""")

# Free-threaded Python (opt-in)
Pythonx.uv_init("""
[project]
name = "project"
version = "0.0.0"
requires-python = "==3.14.*"
""", python: "3.14t")

Validation

Tested on macOS aarch64. uv downloaded cpython-3.14.0rc1+freethreaded-macos-aarch64-none and confirmed:

Python 3.14.0rc1 free-threading build | GIL disabled: 1

Parallelism benchmark

8 concurrent tasks running CPU-bound pure Python work:

Pythonx.uv_init(
  """
  [project]
  name = "test-free-threaded"
  version = "0.0.0"
  requires-python = "==3.14.*"
  """,
  python: "3.14t"
)

cpu_work = """
total = 0
for i in range(2_000_000):
    total += i
total
"""

# Sequential baseline
t0 = System.monotonic_time(:millisecond)

for _ <- 1..8 do
  Pythonx.eval(cpu_work, %{})
end

sequential_ms = System.monotonic_time(:millisecond) - t0
IO.puts("Sequential (8 tasks):  #{sequential_ms} ms")

# Concurrent
t0 = System.monotonic_time(:millisecond)

tasks =
  for _ <- 1..8 do
    Task.async(fn -> Pythonx.eval(cpu_work, %{}) end)
  end

Task.await_many(tasks, 60_000)
concurrent_ms = System.monotonic_time(:millisecond) - t0
IO.puts("Concurrent (8 tasks):  #{concurrent_ms} ms")

speedup = sequential_ms / max(concurrent_ms, 1)
IO.puts("Speedup:               #{Float.round(speedup, 2)}x")

Results:

┌────────────┬────────┐
│    Mode    │  Time  │
├────────────┼────────┤
│ Sequential │ 531 ms │
├────────────┼────────┤
│ Concurrent │ 124 ms │
├────────────┼────────┤
│ Speedup    │ 4.28x  │
└────────────┴────────┘

True parallelism confirmed — with standard Python this would be ~1.0x since the GIL serializes pure Python work.

Cache separation

Different :python values produce different cache directories:
- No option: c4mnqgs63q7e66whs4cuoeftui
- "3.14t": wkfkw7orrgqor6yjyu37kglmgu

Backwards compatibility

All 74 existing tests pass unchanged (8 doctests + 66 tests, 0 failures).

Caveats

- Not all Python packages support free-threading yet (tracker)
- Users must ensure their Python code is thread-safe when using free-threaded Python with concurrent Elixir callers
- ~5-10% single-thread overhead in free-threaded mode vs standard Python 3.14