Skip to main content
NimbusKV LogoNimbusKV

Guides & Tutorials

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

v3.1.1
Updated from GitHub 10/18/2026
Edit on GitHub
Installation & Setup

Install NimbusKV from PyPI, configure SQLite, Redis extras, and local development test suites.

Read guide
Free-Threaded Python Setup

Configure CPython 3.13t/3.14t with PYTHON_GIL=0 for true multi-core parallel read execution.

Read guide
Upgrading to v3.1.0

Understand the deterministic write mutex overhaul, ReentrantWriteError, and atomic notifications.

Read guide
Migrating from LiveDict

Transition smoothly from the legacy LiveDict library to the modern NimbusKV API.

Read guide

1. Installation & Environment Setup

NimbusKV requires Python 3.9+ and has minimal dependencies. It is published on PyPI.

Standard In-Memory / SQLite Installation
$pip install nimbuskv
With Redis Persistence Backend
$pip install "nimbuskv[redis]"

To run from source or contribute to the library:

Terminal
git clone https://github.com/NimbusKV/NimbusKV.git
cd NimbusKV
pip install -e ".[dev]"
pytest tests/ -v

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
import sys
import sysconfig
from nimbuskv import NimbusKV
# Verify free-threading build
is_nogil = sysconfig.get_config_var("Py_GIL_DISABLED") == 1
print(f"Free-threaded build: {is_nogil}")
with NimbusKV() as store:
    store.set("status", "parallel-ready")
    print(store.get("status"))

3. Upgrading to v3.1.0

NimbusKV v3.1.0 is an infrastructure-hardening release. Public API signatures remain backwards compatible with v3.0.x, but two critical behavioral improvements were introduced:

1. Deterministic Write Mutex

Prior versions (v3.0.0 through v3.0.1) used an optimistic CAS retry loop. Under hot keys with high thread counts, this caused retry storms and CPU churn. v3.1.0 replaces CAS with a single short write mutex, giving deterministic throughput.

2. ReentrantWriteError Detection

Attempting to call write operations (set(), delete()) from inside an atomic() or mutate() callback now raises an immediate ReentrantWriteError rather than deadlocking.

upgrade_example.py
from nimbuskv import NimbusKV
from nimbuskv.exceptions import ReentrantWriteError
store = NimbusKV()
store.set("counter", 10)
# Correct atomic pattern:
def increment(val):
    return (val or 0) + 1
store.atomic("counter", increment)
print(store.get("counter"))  # 11

4. Migrating from LiveDict

If you are upgrading an existing codebase from the legacy livedict package, the primary change is the package and class name:

migration_diff.py
# Before (LiveDict legacy)
# from livedict import LiveDict
# ld = LiveDict()
# After (NimbusKV v3)
from nimbuskv import NimbusKV
with NimbusKV() as ld:
    ld.set("session_key", {"user_id": 42}, ttl=3600)
    print(ld.get("session_key"))
Drop-in Compatibility Note

NimbusKV supports both dictionary-style access (ld["key"] = val) and explicit method calls (ld.set(key, val, ttl=...)). For TTL expirations and reactive events, the explicit method syntax is recommended.