Install & Compatibility
Where this runs
tested against v3.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cmake_dir
✓ from nanobind import cmake_dir
✗ import your_nanobind_module
include_dir
✓ from nanobind import include_dir
source_dir
✓ from nanobind import source_dir
This quickstart demonstrates the Python side of interacting with a nanobind-generated extension. It assumes a C++ module (e.g., `_my_ext_impl`) has been built and exposed via a Python package (`my_ext`), following the recommended packaging guidelines. The C++ code defines a simple 'hello' function, which is then imported and called from Python.
# Assuming you have built a nanobind extension named 'my_ext'
# For example, with C++ code like:
# NB_MODULE(my_ext_impl, m) { m.def("hello", []() { return "Hello world!"; }); }
# And an __init__.py with: from ._my_ext_impl import hello
import my_ext
message = my_ext.hello()
print(message)
Debug
Known issues
breakingnanobind has a separate ABI version that is not subject to semantic versioning. Upgrades to nanobind (e.g., from 2.1 to 2.2) can introduce ABI incompatibilities, requiring all downstream packages that use nanobind to be rebuilt. This is critical for projects relying on pre-built binary wheels from other nanobind-dependent libraries.fixEnsure all dependent nanobind-based modules are rebuilt against the same nanobind version. Monitor nanobind's ABI version in the changelog.
affects: All versions, especially between minor releases (X.Y.Z where Y changes).
breakingSupport for Python 3.8 was officially dropped with nanobind version 2.10.0, which was released in December 2025. Projects using older Python versions must either upgrade their Python environment or pin nanobind to a version prior to 2.10.0.fixUpgrade your Python environment to 3.9+ or use nanobind < 2.10.0.
affects: >=2.10.0
breakingIn nanobind 2.0.0, the `nb::enum_<T>()` binding declaration changed to create `enum.Enum` or `enum.IntEnum`-derived types. Code that previously cast enum entries directly to integers might break if the enum is not `enum.IntEnum`-derived. Accessing `my_enum_entry.value` is the recommended approach.fixUpdate code to access `my_enum_entry.value` for integer representation, especially if the enum is not guaranteed to be `enum.IntEnum`-derived.
affects: >=2.0.0
gotchaWarnings about 'leaked instances/functions/types' can occur, often indicating underlying reference counting issues within the binding code. This can be exacerbated by Python type annotations or improper `Py_INCREF` usage, leading to resource leaks during interpreter finalization.fixReview nanobind's documentation on reference leaks and ensure correct ownership management. When possible, use nanobind wrappers over direct Python C API calls. Consider adding cleanup handlers if issues persist with type annotation caches.
affects: All versions
gotchaConflicting type bindings can arise if multiple nanobind-based extensions expose or interact with the same C++ types (e.g., `std::latch`) inconsistently. nanobind will warn about such conflicts (e.g., `RuntimeWarning: nanobind: type 'latch' was already registered!`), which can lead to unpredictable behavior or crashes.fixEnsure that if common types are exposed across multiple extensions, their bindings are consistent. Consider using opaque types or isolating namespaces where conflicts are unavoidable.
affects: All versions
Upgrade
Version history
3.0.1latest on PyPI · released Aug 27, 2026
Audit
Dependencies
PythonrequiredRuntime, requires Python 3.9+ or PyPy 7.3.10+.
CMakerequiredBuild-time, requires CMake 3.15+ to compile nanobind extensions.
C++17 CompilerrequiredBuild-time, requires Clang 8+, GCC 8+, MSVC2019+, MinGW-w64, Intel ICX, or CUDA NVCC.
scikit-build-corerequiredBuild-time backend for creating Python packages with nanobind extensions.