Free-Threaded Python Setup

Practical setup guides, performance tuning for free-threaded Python, migration workflows, and upgrade notes.

v3.1.1

Updated from GitHub 10/18/2026

2. Free-Threaded Python (3.13t/3.14t)

NimbusKV automatically detects free-threaded Python builds at runtime. On standard GIL Python, read operations run safely under the GIL; on free-threaded builds, concurrent reads execute with genuine parallel multi-core performance.

Important: PYTHON_GIL=0 Environment Requirement

NimbusKV relies on MagicStack's immutables library for its HAMT persistent map. Because C-extensions can accidentally re-enable the GIL, you must set PYTHON_GIL=0 (or run Python with python -X gil=0) to prevent GIL re-enablement.

Running your application with GIL disabled:

$PYTHON_GIL=0 python your_app.py

Alternative CLI flag:

$python -X gil=0 your_app.py

check_gil.py

1import sys
2import sysconfig
3from nimbuskv import NimbusKV
4
5# Verify free-threading build
6is_nogil = sysconfig.get_config_var("Py_GIL_DISABLED") == 1
7print(f"Free-threaded build: {is_nogil}")
8
9with NimbusKV() as store:
10    store.set("status", "parallel-ready")
11    print(store.get("status"))