1. 项目概述为什么我们需要 nanobind如果你是一个C开发者同时又需要和Python生态打交道那么“绑定”这个词对你来说一定不陌生。简单来说绑定就是在Python里能直接调用你用C写的函数和类让Python享受到C的高性能同时让C代码能融入Python庞大的库生态。过去几年pybind11几乎是这个领域的标准答案它功能强大社区活跃。但用过的人都知道它的编译速度尤其是在大型项目里实在有点让人头疼。每次改几行代码等编译的时间够喝杯咖啡了。这就是nanobind出现的背景。它自称是一个“轻量级”的C到Python绑定库目标非常明确在提供与pybind11相近功能的同时追求极致的编译速度和运行时性能。我第一次接触它是因为一个实时图像处理项目Python前端需要调用一个复杂的C算法库。用pybind11时增量编译一次模块需要近一分钟严重拖慢了调试效率。换成nanobind后同样的改动编译时间缩短到了十秒以内这种提升是立竿见影的。所以nanobind适合谁它非常适合那些对编译效率敏感、项目模块较多、或者希望绑定代码尽可能简洁的开发者。无论是做科学计算、游戏引擎脚本、还是高性能算法库的封装如果你正在被漫长的编译时间困扰那么nanobind值得你花时间了解一下。接下来我会结合多个实际示例带你从零开始掌握它的核心用法和那些官方文档里不会明说的细节。2. 核心设计思路与工具选型解析2.1 nanobind 与 pybind11 的核心理念差异要理解nanobind怎么用先得明白它和pybind11在设计上的根本不同。pybind11采用了大量模板元编程和编译期计算这赋予了它强大的灵活性和表达能力但代价就是编译器需要处理极其复杂的模板实例化导致编译速度慢并且生成的二进制文件体积较大。nanobind则走了另一条路。它的设计哲学是“运行时优先”。它大量使用C17的constexpr和特性检测将许多pybind11在编译期完成的工作转移到了运行时。这听起来可能效率低但实际上现代CPU的运行时开销极小而换来的编译速度提升却是巨大的。此外nanobind在内存管理和对象模型上也做了优化例如它默认使用更高效的“偷窃引用”策略减少了Python和C边界上的引用计数操作。简单类比pybind11像是一个功能齐全的瑞士军刀什么都有但展开稍慢nanobind则像一把专门为你当前任务打磨好的快刀出鞘迅速直指要害。对于90%的绑定需求nanobind的“功能子集”已经完全够用。2.2 环境准备与安装实战理论说再多不如动手装一个。nanobind的安装非常“现代”它推荐使用CMake的FetchContent模块这意味你不需要提前下载源码构建系统会自动搞定。首先确保你的环境符合要求编译器支持C17的编译器GCC 7, Clang 5, MSVC 2019。Python3.8 及以上版本。建议使用venv或conda创建独立的虚拟环境。构建系统CMake 3.16。这是目前C项目的事实标准nanobind深度集成其中。在你的项目CMakeLists.txt中加入以下内容cmake_minimum_required(VERSION 3.16) project(MyNanobindProject) # 设置C标准 set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 关键步骤获取nanobind include(FetchContent) FetchContent_Declare( nanobind GIT_REPOSITORY https://github.com/wjakob/nanobind.git GIT_TAG v2.0.0 # 建议指定一个稳定版本标签 ) FetchContent_MakeAvailable(nanobind) # 添加你的绑定模块 add_library(my_module MODULE src/bindings.cpp) target_link_libraries(my_module nanobind) # 在Windows上需要特别指定后缀为.pyd set_target_properties(my_module PROPERTIES SUFFIX .pyd PREFIX )注意FetchContent会在配置阶段下载代码如果网络环境不稳定可能会失败。你也可以选择将nanobind作为子模块git submodule添加到你的项目中这样更稳定。命令是git submodule add https://github.com/wjakob/nanobind.git extern/nanobind然后在CMake中用add_subdirectory(extern/nanobind)替代FetchContent。配置并生成构建文件后使用cmake --build .即可编译。你会立刻感受到编译速度的不同。我第一次构建一个简单的绑定模块nanobind比pybind11快了将近3倍。3. 从零开始第一个绑定示例让我们从一个最简单的“Hello World”开始感受一下nanobind的语法。创建文件src/bindings.cpp#include nanobind/nanobind.h namespace nb nanobind; // 1. 绑定一个简单的函数 int add(int a, int b) { return a b; } // 2. 绑定一个简单的类 class Pet { public: Pet(const std::string name) : name(name) {} void setName(const std::string name_) { name name_; } const std::string getName() const { return name; } private: std::string name; }; // 3. 模块初始化函数 NB_MODULE(my_module, m) { // 绑定函数 m.def(add, add, nb::arg(a), nb::arg(b), A function which adds two numbers); // 绑定类 nb::class_Pet(m, Pet) .def(nb::initconst std::string ()) .def(setName, Pet::setName) .def(getName, Pet::getName); }编译成功后在Python中就可以这样使用import my_module print(my_module.add(5, 3)) # 输出: 8 my_pet my_module.Pet(Molly) print(my_pet.getName()) # 输出: Molly my_pet.setName(Chloe) print(my_pet.getName()) # 输出: Chloe可以看到nanobind的基本API和pybind11非常相似NB_MODULE替代了PYBIND11_MODULEnb::class_替代了pybind11::class_。这种设计降低了迁移成本。但细微之处见真章nanobind的nb::arg()用于指定参数名让生成的函数文档更清晰。4. 核心功能深度解析与进阶用法掌握了基础我们来深入几个核心且常用的功能点。这些是你在实际项目中几乎一定会遇到的。4.1 类型转换与STL容器支持在C和Python之间传递数据类型转换是基石。nanobind内置了对标准类型和许多STL容器的支持。#include nanobind/nanobind.h #include nanobind/stl/string.h // 需要单独包含STL容器的头文件 #include nanobind/stl/vector.h #include nanobind/stl/unordered_map.h #include complex namespace nb nanobind; // 自动类型转换示例 std::string greet(const std::string name) { return Hello, name !; } // 传递和返回STL容器 std::vectorfloat process_data(const std::vectorint input) { std::vectorfloat output; output.reserve(input.size()); for (int x : input) { output.push_back(static_castfloat(x) * 0.5f); } return output; } // 使用字典unordered_map std::unordered_mapstd::string, int count_words(const std::vectorstd::string words) { std::unordered_mapstd::string, int counts; for (const auto w : words) { counts[w]; } return counts; } // 支持复数 std::complexdouble complex_add(std::complexdouble a, std::complexdouble b) { return a b; } NB_MODULE(containers_demo, m) { m.def(greet, greet); m.def(process_data, process_data); m.def(count_words, count_words); m.def(complex_add, complex_add); }Python端调用毫无障碍import containers_demo as cd print(cd.greet(World)) # Hello, World! result cd.process_data([1, 2, 3, 4]) print(result) # [0.5, 1.0, 1.5, 2.0] (list of float) word_counts cd.count_words([apple, banana, apple, orange]) print(word_counts) # {apple: 2, banana: 1, orange: 1} (dict) c cd.complex_add(12j, 34j) print(c) # (46j)实操心得nanobind对STL容器的支持是“零拷贝”或“高效拷贝”的。对于std::vector这样的连续内存容器在传递时可能会直接引用底层数据避免了不必要的复制这对性能至关重要。但要注意从Python列表创建std::vector时必然会发生一次拷贝。4.2 高级类绑定属性、继承与动态属性绑定类时我们常常需要暴露属性、处理继承关系甚至模拟Python的动态特性。#include nanobind/nanobind.h #include nanobind/stl/string.h #include nanobind/operators.h // 用于绑定运算符 namespace nb nanobind; // 基类 class Animal { public: Animal(const std::string name) : name(name) {} virtual ~Animal() default; virtual std::string speak() const { return (silence); } std::string getName() const { return name; } protected: std::string name; }; // 派生类 class Dog : public Animal { public: Dog(const std::string name) : Animal(name) {} std::string speak() const override { return name says Woof!; } void wagTail() { /* ... */ } }; // 一个带有读写属性和运算符的类 class Vector2D { public: float x, y; Vector2D(float x, float y) : x(x), y(y) {} // 运算符重载 Vector2D operator(const Vector2D other) const { return Vector2D(x other.x, y other.y); } bool operator(const Vector2D other) const { return x other.x y other.y; } // 一个计算属性只读 float magnitude() const { return std::sqrt(x*x y*y); } }; NB_MODULE(advanced_class, m) { // 绑定基类Animal nb::class_Animal(m, Animal) .def(nb::initconst std::string ()) .def(speak, Animal::speak) .def_prop_ro(name, Animal::getName); // 将getName暴露为只读属性“name” // 绑定派生类Dog并指定继承关系 nb::class_Dog, Animal(m, Dog) .def(nb::initconst std::string ()) .def(wag_tail, Dog::wagTail); // speak方法从基类自动继承并正确调用派生类的实现 // 绑定Vector2D展示属性和运算符 nb::class_Vector2D(m, Vector2D) .def(nb::initfloat, float()) .def_rw(x, Vector2D::x) // 读写属性 .def_rw(y, Vector2D::y) .def_prop_ro(magnitude, Vector2D::magnitude) // 只读属性 .def(nb::self nb::self) // 绑定运算符 .def(nb::self nb::self); // 绑定运算符 // 动态添加一个函数到模块中不推荐滥用但有时有用 m.def(dynamic_func, []() { return I was added dynamically; }); }Python测试代码import advanced_class as ac animal ac.Animal(Generic) print(animal.speak()) # (silence) print(animal.name) # Generic dog ac.Dog(Buddy) print(dog.speak()) # Buddy says Woof! print(isinstance(dog, ac.Animal)) # True v1 ac.Vector2D(3, 4) v2 ac.Vector2D(1, 2) v3 v1 v2 print(v3.x, v3.y) # 4.0 6.0 print(v1.magnitude()) # 5.0 v1.x 10 # 可以修改属性 print(v1.x) # 10.0 print(ac.dynamic_func()) # I was added dynamically注意事项绑定继承关系时务必使用nb::class_Derived, Base的语法。nanobind会自动处理基类方法的查找和虚函数调用确保在Python中调用dog.speak()时调用的是Dog::speak()而不是Animal::speak()。这是通过C的RTTI运行时类型识别实现的虽然有一点点开销但保证了正确性。4.3 内存管理与智能指针集成C的内存管理尤其是涉及多态对象时是绑定的难点。nanobind对std::unique_ptr和std::shared_ptr有很好的支持。#include nanobind/nanobind.h #include nanobind/stl/unique_ptr.h #include nanobind/stl/shared_ptr.h #include memory namespace nb nanobind; class Resource { public: Resource(int id) : id(id) { std::cout Resource id created.\n; } ~Resource() { std::cout Resource id destroyed.\n; } int getId() const { return id; } private: int id; }; // 工厂函数返回unique_ptr std::unique_ptrResource create_unique_resource(int id) { return std::make_uniqueResource(id); } // 接受shared_ptr作为参数的函数 void use_shared_resource(const std::shared_ptrResource res) { if (res) { std::cout Using resource id: res-getId() std::endl; } } // 返回shared_ptr的函数 std::shared_ptrResource get_shared_resource() { static auto resource std::make_sharedResource(999); return resource; } NB_MODULE(smart_ptr_demo, m) { // 绑定类时可以指定持有的智能指针类型 nb::class_Resource, std::shared_ptrResource(m, Resource) .def(nb::initint()) .def(get_id, Resource::getId); m.def(create_unique_resource, create_unique_resource); m.def(use_shared_resource, use_shared_resource); m.def(get_shared_resource, get_shared_resource); }Python端的使用非常直观import smart_ptr_demo as spd # 获取一个unique_ptr当Python对象被垃圾回收时C对象自动删除 unique_res spd.create_unique_resource(1) print(unique_res.get_id()) # 1 # unique_res 离开作用域或被del后会打印“Resource 1 destroyed.” # 获取一个shared_ptr shared_res spd.get_shared_resource() print(shared_res.get_id()) # 999 spd.use_shared_resource(shared_res) # Using resource id: 999 # 多个Python变量可以持有同一个shared_ptr引用计数会正确工作 alias shared_res del shared_res # 此时C对象不会销毁因为alias还持有引用 print(alias.get_id()) # 999 # 当alias也被删除后如果引用计数为0才会打印“Resource 999 destroyed.”核心要点当你在nb::class_中指定了智能指针类型如std::shared_ptrResourcenanobind会确保所有涉及该类对象的传递都使用该智能指针。这意味着从C返回的shared_ptr在Python端是安全的反之从Python传递给C的Resource对象也会被自动转换为shared_ptr。这彻底解决了跨语言边界的对象生命周期管理难题。5. 性能优化与底层交互nanobind的卖点是性能我们来看看如何充分利用它。5.1 缓冲区协议Buffer Protocol与NumPy集成对于数值计算在Python的NumPy数组和C的原始内存块之间进行零拷贝传递是终极性能需求。nanobind通过支持Python的缓冲区协议PEP 3118来实现这一点。#include nanobind/nanobind.h #include nanobind/ndarray.h // 关键头文件 #include algorithm namespace nb nanobind; using namespace nb::literals; // 用于使用“_a”字面量指定参数名 // 接受一个二维float数组例如NumPy数组并就地修改 void double_matrix(nb::ndarrayfloat, nb::ndim2 array) { // 获取形状、步长和原始指针 size_t rows array.shape(0); size_t cols array.shape(1); float* data array.data(); // 确保数组是C连续且可写的 if (!array.is_c_contiguous()) { throw std::runtime_error(Array must be C-contiguous); } for (size_t i 0; i rows * cols; i) { data[i] * 2.0f; } } // 从C创建并返回一个新的ndarray nb::ndarraynb::numpy, float create_zeros(int rows, int cols) { // 分配内存。注意这里的内存管理将交给Python的引用计数。 float* data new float[rows * cols](); // 值初始化为零 std::fill(data, data rows * cols, 0.0f); // 创建ndarray对象并指定当Python对象销毁时调用删除器 size_t shape[2] {static_castsize_t(rows), static_castsize_t(cols)}; size_t strides[2] {cols * sizeof(float), sizeof(float)}; // nb::ndarray的构造函数数据指针维度形状步长所有者Python capsule数据类型 nb::capsule owner(data, [](void* p) noexcept { delete[] (float*)p; }); return nb::ndarraynb::numpy, float(data, 2, shape, owner); } NB_MODULE(ndarray_demo, m) { m.def(double_matrix, double_matrix, array_a); m.def(create_zeros, create_zeros, rows_a, cols_a); }在Python中你可以无缝使用NumPyimport numpy as np import ndarray_demo as nd # 创建一个NumPy数组 arr np.array([[1.0, 2.0], [3.0, 4.0]], dtypenp.float32) print(Before:, arr) nd.double_matrix(arr) # 零拷贝直接修改原数组数据 print(After:, arr) # [[2., 4.], [6., 8.]] # 从C接收一个数组 zeros nd.create_zeros(3, 4) print(zeros) print(type(zeros)) # class numpy.ndarray print(zeros.shape) # (3, 4)性能关键nb::ndarray模板的第一个参数可以是nb::numpy、nb::pytorch等以指定数组的预期来源这有助于进行更严格的检查。使用nb::ndarray进行交互避免了通过Python列表再转换成std::vector的拷贝开销对于大型数组性能差异是数量级的。5.2 线程安全与全局解释器锁GILC代码是原生线程而Python有全局解释器锁GIL。在C线程中回调Python或操作Python对象时必须手动管理GIL。#include nanobind/nanobind.h #include thread #include vector namespace nb nanobind; void heavy_computation(int iterations, nb::object callback) { // 这个函数可能在C创建的线程中被调用 // 在调用任何Python API之前必须获取GIL nb::gil_scoped_acquire acquire; // 构造时获取GIL析构时释放 for (int i 0; i iterations; i) { // 模拟计算 std::this_thread::sleep_for(std::chrono::milliseconds(10)); // 回调Python函数报告进度 callback(i); } // acquire 对象析构自动释放GIL } void run_in_parallel(int task_count, nb::object py_func) { std::vectorstd::thread threads; for (int i 0; i task_count; i) { threads.emplace_back([i, py_func]() { // 每个线程需要独立获取GIL来调用Python nb::gil_scoped_acquire acquire; py_func(i); }); } for (auto t : threads) { t.join(); } } NB_MODULE(threading_demo, m) { m.def(heavy_computation, heavy_computation, iterations_a, callback_a); m.def(run_in_parallel, run_in_parallel, task_count_a, func_a); }Python脚本import threading_demo as td import threading def progress(i): # 这个函数会在C线程中被调用 print(fThread {threading.get_ident()}: Iteration {i}) print(Main thread:, threading.get_ident()) td.heavy_computation(5, progress) def task_func(task_id): print(fParallel task {task_id} in thread {threading.get_ident()}) td.run_in_parallel(4, task_func)重要警告忘记获取GIL就在非主线程中操作Python对象是导致Python解释器崩溃的最常见原因之一。nb::gil_scoped_acquire是你的安全护栏。同样如果一段C代码长时间运行且不调用Python应该在开始处使用nb::gil_scoped_release临时释放GIL让其他Python线程得以运行。6. 构建、打包与分发实战写好了绑定代码如何把它变成一个可以方便分发的Python包现代Python生态主要使用pip和setuptools。6.1 使用 pyproject.toml 和 setuptools这是目前最推荐的方式。你需要一个pyproject.toml文件和一个setup.py或setup.cfg。目录结构my_extension/ ├── pyproject.toml ├── setup.py ├── my_extension/ │ ├── __init__.py │ └── core.cpp (你的绑定代码) └── CMakeLists.txtpyproject.toml:[build-system] requires [setuptools61.0, wheel, scikit-build-core0.5] build-backend setuptools.build_metasetup.py:from setuptools import setup, Extension from setuptools.command.build_ext import build_ext import subprocess import os # 自定义构建扩展类用于调用CMake class CMakeExtension(Extension): def __init__(self, name): super().__init__(name, sources[]) class CMakeBuild(build_ext): def run(self): for ext in self.extensions: self.build_extension(ext) def build_extension(self, ext): extdir os.path.abspath(os.path.dirname(self.get_ext_fullpath(ext.name))) cmake_args [ f-DCMAKE_LIBRARY_OUTPUT_DIRECTORY{extdir}, f-DPYTHON_EXECUTABLE{sys.executable}, -DCMAKE_BUILD_TYPERelease ] build_args [--config, Release] # 支持多核编译 import multiprocessing build_args [--, f-j{multiprocessing.cpu_count()}] # 创建构建目录 build_temp os.path.join(self.build_temp, ext.name) os.makedirs(build_temp, exist_okTrue) subprocess.run([cmake, -S, ., -B, build_temp] cmake_args, checkTrue) subprocess.run([cmake, --build, build_temp] build_args, checkTrue) setup( namemy_extension, version0.1.0, ext_modules[CMakeExtension(my_extension)], cmdclass{build_ext: CMakeBuild}, zip_safeFalse, )CMakeLists.txt(项目根目录):cmake_minimum_required(VERSION 3.16) project(my_extension LANGUAGES CXX) # 查找Python和nanobind find_package(Python 3.8 REQUIRED COMPONENTS Development.Module) include(FetchContent) FetchContent_Declare(nanobind GIT_REPOSITORY https://github.com/wjakob/nanobind.git GIT_TAG v2.0.0) FetchContent_MakeAvailable(nanobind) # 添加你的扩展模块 add_library(my_extension MODULE my_extension/core.cpp) target_link_libraries(my_extension nanobind) set_target_properties(my_extension PROPERTIES CXX_VISIBILITY_PRESET hidden VISIBILITY_INLINES_HIDDEN ON PREFIX SUFFIX .so # Linux/MacWindows上为“.pyd” )配置好后在项目根目录执行pip install .setuptools会自动调用CMake完成编译和安装。6.2 使用 scikit-build-core (更现代的方式)scikit-build-core是一个更精简、基于pyproject.toml的构建后端它直接集成了CMake。pyproject.toml:[build-system] requires [scikit-build-core0.5] build-backend scikit_build_core.build [project] name my_extension version 0.1.0 [tool.scikit-build] cmake.args [-DCMAKE_BUILD_TYPERelease]无需setup.py。你的CMakeLists.txt和之前一样。然后直接运行pip install .即可。这种方式更加简洁是未来的趋势。打包避坑指南ABI兼容性在Linux上编译扩展的Python版本、编译器版本和GLIBC版本必须与运行环境匹配。使用manylinuxDocker镜像如manylinux2014_x86_64进行构建可以保证广泛的兼容性。RPATH问题在MacOS上编译出的.so文件可能有绝对路径的依赖。在CMake中设置set(CMAKE_INSTALL_RPATH loader_path)可以缓解。调试符号在开发时使用-DCMAKE_BUILD_TYPEDebug并确保链接了Python的调试库这样可以在C代码中设置断点。版本锁定在FetchContent_Declare中指定nanobind的具体版本标签如v2.0.0避免因主分支更新导致构建失败。7. 常见问题排查与调试技巧即使按照指南操作也难免会遇到问题。这里记录了一些我踩过的坑和解决方法。7.1 编译错误排查表错误信息可能原因解决方案fatal error: nanobind/nanobind.h file not found头文件路径未包含。确保CMake正确引入了nanobind并且target_link_libraries你的目标链接到了nanobind。undefined symbol: _PyArg_ParseStackPython版本不匹配或链接了错误的Python库。检查find_package(Python)找到的版本是否与你当前使用的Python环境一致。在虚拟环境中构建时尤其要注意。error: static assertion failed: ... is not a class/struct/union尝试绑定的类型不是完整的类类型。确保在绑定该类之前其定义是完整的即已经看到了类的全部内容。通常需要将绑定代码放在类定义的头文件之后。模块导入时ImportError: dynamic module does not define module export function模块初始化函数名不匹配。NB_MODULE(module_name, m)中的module_name必须与add_library的目标名以及Python中import的名字完全一致。运行时TypeError: No to_python (by-value) converter found for C type: ...尝试返回或传递了一个nanobind不认识的C类型。为该类型编写自定义的类型转换器或者将其改为使用智能指针持有如果适用。更常见的是忘记包含对应STL容器的头文件如#include nanobind/stl/vector.h。7.2 调试技巧在C中打印调试信息在绑定代码中使用std::cout或printf。输出会显示在Python运行的标准输出/错误流中。这对于跟踪函数调用顺序和参数值非常有用。使用Python的inspect模块导入模块后使用inspect.signature()查看绑定函数的签名确保参数名和类型符合预期。启用Python的faulthandler当解释器因非法内存访问而崩溃时faulthandler可以打印出崩溃时的Python堆栈。在程序开头import faulthandler; faulthandler.enable()。在CMake中开启详细编译输出在CMake配置时加上-DCMAKE_VERBOSE_MAKEFILE:BOOLON或者在构建时使用make VERBOSE1或cmake --build . --verbose可以查看完整的编译和链接命令有助于发现链接库缺失等问题。隔离测试创建一个最小的、只包含问题功能的.cpp文件进行绑定测试排除项目中其他代码的干扰。7.3 性能分析如果你怀疑绑定层本身成了性能瓶颈通常不会但大型对象频繁传递时可能使用Python的cProfile模块分析函数调用开销。对于特定的C函数可以在其前后使用Python的time.perf_counter_ns()进行纳秒级计时。考虑是否过度使用了“按值返回”。对于大型对象使用nb::rv_policy::reference_internal或返回智能指针可能更高效但要注意生命周期管理。最后切换到nanobind本身就是一次显著的性能提升尤其是开发体验上的提升。它让“编译-测试”的循环快得多使得基于C扩展的Python项目开发变得更加流畅愉快。从我个人的项目经验来看除非你需要pybind11某些极其小众的特性否则nanobind在性能、编译速度和代码简洁性上的综合优势是决定性的。
nanobind：极速编译的C++/Python绑定库，性能与开发效率双提升
发布时间：2026/7/16 1:18:38
1. 项目概述为什么我们需要 nanobind如果你是一个C开发者同时又需要和Python生态打交道那么“绑定”这个词对你来说一定不陌生。简单来说绑定就是在Python里能直接调用你用C写的函数和类让Python享受到C的高性能同时让C代码能融入Python庞大的库生态。过去几年pybind11几乎是这个领域的标准答案它功能强大社区活跃。但用过的人都知道它的编译速度尤其是在大型项目里实在有点让人头疼。每次改几行代码等编译的时间够喝杯咖啡了。这就是nanobind出现的背景。它自称是一个“轻量级”的C到Python绑定库目标非常明确在提供与pybind11相近功能的同时追求极致的编译速度和运行时性能。我第一次接触它是因为一个实时图像处理项目Python前端需要调用一个复杂的C算法库。用pybind11时增量编译一次模块需要近一分钟严重拖慢了调试效率。换成nanobind后同样的改动编译时间缩短到了十秒以内这种提升是立竿见影的。所以nanobind适合谁它非常适合那些对编译效率敏感、项目模块较多、或者希望绑定代码尽可能简洁的开发者。无论是做科学计算、游戏引擎脚本、还是高性能算法库的封装如果你正在被漫长的编译时间困扰那么nanobind值得你花时间了解一下。接下来我会结合多个实际示例带你从零开始掌握它的核心用法和那些官方文档里不会明说的细节。2. 核心设计思路与工具选型解析2.1 nanobind 与 pybind11 的核心理念差异要理解nanobind怎么用先得明白它和pybind11在设计上的根本不同。pybind11采用了大量模板元编程和编译期计算这赋予了它强大的灵活性和表达能力但代价就是编译器需要处理极其复杂的模板实例化导致编译速度慢并且生成的二进制文件体积较大。nanobind则走了另一条路。它的设计哲学是“运行时优先”。它大量使用C17的constexpr和特性检测将许多pybind11在编译期完成的工作转移到了运行时。这听起来可能效率低但实际上现代CPU的运行时开销极小而换来的编译速度提升却是巨大的。此外nanobind在内存管理和对象模型上也做了优化例如它默认使用更高效的“偷窃引用”策略减少了Python和C边界上的引用计数操作。简单类比pybind11像是一个功能齐全的瑞士军刀什么都有但展开稍慢nanobind则像一把专门为你当前任务打磨好的快刀出鞘迅速直指要害。对于90%的绑定需求nanobind的“功能子集”已经完全够用。2.2 环境准备与安装实战理论说再多不如动手装一个。nanobind的安装非常“现代”它推荐使用CMake的FetchContent模块这意味你不需要提前下载源码构建系统会自动搞定。首先确保你的环境符合要求编译器支持C17的编译器GCC 7, Clang 5, MSVC 2019。Python3.8 及以上版本。建议使用venv或conda创建独立的虚拟环境。构建系统CMake 3.16。这是目前C项目的事实标准nanobind深度集成其中。在你的项目CMakeLists.txt中加入以下内容cmake_minimum_required(VERSION 3.16) project(MyNanobindProject) # 设置C标准 set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 关键步骤获取nanobind include(FetchContent) FetchContent_Declare( nanobind GIT_REPOSITORY https://github.com/wjakob/nanobind.git GIT_TAG v2.0.0 # 建议指定一个稳定版本标签 ) FetchContent_MakeAvailable(nanobind) # 添加你的绑定模块 add_library(my_module MODULE src/bindings.cpp) target_link_libraries(my_module nanobind) # 在Windows上需要特别指定后缀为.pyd set_target_properties(my_module PROPERTIES SUFFIX .pyd PREFIX )注意FetchContent会在配置阶段下载代码如果网络环境不稳定可能会失败。你也可以选择将nanobind作为子模块git submodule添加到你的项目中这样更稳定。命令是git submodule add https://github.com/wjakob/nanobind.git extern/nanobind然后在CMake中用add_subdirectory(extern/nanobind)替代FetchContent。配置并生成构建文件后使用cmake --build .即可编译。你会立刻感受到编译速度的不同。我第一次构建一个简单的绑定模块nanobind比pybind11快了将近3倍。3. 从零开始第一个绑定示例让我们从一个最简单的“Hello World”开始感受一下nanobind的语法。创建文件src/bindings.cpp#include nanobind/nanobind.h namespace nb nanobind; // 1. 绑定一个简单的函数 int add(int a, int b) { return a b; } // 2. 绑定一个简单的类 class Pet { public: Pet(const std::string name) : name(name) {} void setName(const std::string name_) { name name_; } const std::string getName() const { return name; } private: std::string name; }; // 3. 模块初始化函数 NB_MODULE(my_module, m) { // 绑定函数 m.def(add, add, nb::arg(a), nb::arg(b), A function which adds two numbers); // 绑定类 nb::class_Pet(m, Pet) .def(nb::initconst std::string ()) .def(setName, Pet::setName) .def(getName, Pet::getName); }编译成功后在Python中就可以这样使用import my_module print(my_module.add(5, 3)) # 输出: 8 my_pet my_module.Pet(Molly) print(my_pet.getName()) # 输出: Molly my_pet.setName(Chloe) print(my_pet.getName()) # 输出: Chloe可以看到nanobind的基本API和pybind11非常相似NB_MODULE替代了PYBIND11_MODULEnb::class_替代了pybind11::class_。这种设计降低了迁移成本。但细微之处见真章nanobind的nb::arg()用于指定参数名让生成的函数文档更清晰。4. 核心功能深度解析与进阶用法掌握了基础我们来深入几个核心且常用的功能点。这些是你在实际项目中几乎一定会遇到的。4.1 类型转换与STL容器支持在C和Python之间传递数据类型转换是基石。nanobind内置了对标准类型和许多STL容器的支持。#include nanobind/nanobind.h #include nanobind/stl/string.h // 需要单独包含STL容器的头文件 #include nanobind/stl/vector.h #include nanobind/stl/unordered_map.h #include complex namespace nb nanobind; // 自动类型转换示例 std::string greet(const std::string name) { return Hello, name !; } // 传递和返回STL容器 std::vectorfloat process_data(const std::vectorint input) { std::vectorfloat output; output.reserve(input.size()); for (int x : input) { output.push_back(static_castfloat(x) * 0.5f); } return output; } // 使用字典unordered_map std::unordered_mapstd::string, int count_words(const std::vectorstd::string words) { std::unordered_mapstd::string, int counts; for (const auto w : words) { counts[w]; } return counts; } // 支持复数 std::complexdouble complex_add(std::complexdouble a, std::complexdouble b) { return a b; } NB_MODULE(containers_demo, m) { m.def(greet, greet); m.def(process_data, process_data); m.def(count_words, count_words); m.def(complex_add, complex_add); }Python端调用毫无障碍import containers_demo as cd print(cd.greet(World)) # Hello, World! result cd.process_data([1, 2, 3, 4]) print(result) # [0.5, 1.0, 1.5, 2.0] (list of float) word_counts cd.count_words([apple, banana, apple, orange]) print(word_counts) # {apple: 2, banana: 1, orange: 1} (dict) c cd.complex_add(12j, 34j) print(c) # (46j)实操心得nanobind对STL容器的支持是“零拷贝”或“高效拷贝”的。对于std::vector这样的连续内存容器在传递时可能会直接引用底层数据避免了不必要的复制这对性能至关重要。但要注意从Python列表创建std::vector时必然会发生一次拷贝。4.2 高级类绑定属性、继承与动态属性绑定类时我们常常需要暴露属性、处理继承关系甚至模拟Python的动态特性。#include nanobind/nanobind.h #include nanobind/stl/string.h #include nanobind/operators.h // 用于绑定运算符 namespace nb nanobind; // 基类 class Animal { public: Animal(const std::string name) : name(name) {} virtual ~Animal() default; virtual std::string speak() const { return (silence); } std::string getName() const { return name; } protected: std::string name; }; // 派生类 class Dog : public Animal { public: Dog(const std::string name) : Animal(name) {} std::string speak() const override { return name says Woof!; } void wagTail() { /* ... */ } }; // 一个带有读写属性和运算符的类 class Vector2D { public: float x, y; Vector2D(float x, float y) : x(x), y(y) {} // 运算符重载 Vector2D operator(const Vector2D other) const { return Vector2D(x other.x, y other.y); } bool operator(const Vector2D other) const { return x other.x y other.y; } // 一个计算属性只读 float magnitude() const { return std::sqrt(x*x y*y); } }; NB_MODULE(advanced_class, m) { // 绑定基类Animal nb::class_Animal(m, Animal) .def(nb::initconst std::string ()) .def(speak, Animal::speak) .def_prop_ro(name, Animal::getName); // 将getName暴露为只读属性“name” // 绑定派生类Dog并指定继承关系 nb::class_Dog, Animal(m, Dog) .def(nb::initconst std::string ()) .def(wag_tail, Dog::wagTail); // speak方法从基类自动继承并正确调用派生类的实现 // 绑定Vector2D展示属性和运算符 nb::class_Vector2D(m, Vector2D) .def(nb::initfloat, float()) .def_rw(x, Vector2D::x) // 读写属性 .def_rw(y, Vector2D::y) .def_prop_ro(magnitude, Vector2D::magnitude) // 只读属性 .def(nb::self nb::self) // 绑定运算符 .def(nb::self nb::self); // 绑定运算符 // 动态添加一个函数到模块中不推荐滥用但有时有用 m.def(dynamic_func, []() { return I was added dynamically; }); }Python测试代码import advanced_class as ac animal ac.Animal(Generic) print(animal.speak()) # (silence) print(animal.name) # Generic dog ac.Dog(Buddy) print(dog.speak()) # Buddy says Woof! print(isinstance(dog, ac.Animal)) # True v1 ac.Vector2D(3, 4) v2 ac.Vector2D(1, 2) v3 v1 v2 print(v3.x, v3.y) # 4.0 6.0 print(v1.magnitude()) # 5.0 v1.x 10 # 可以修改属性 print(v1.x) # 10.0 print(ac.dynamic_func()) # I was added dynamically注意事项绑定继承关系时务必使用nb::class_Derived, Base的语法。nanobind会自动处理基类方法的查找和虚函数调用确保在Python中调用dog.speak()时调用的是Dog::speak()而不是Animal::speak()。这是通过C的RTTI运行时类型识别实现的虽然有一点点开销但保证了正确性。4.3 内存管理与智能指针集成C的内存管理尤其是涉及多态对象时是绑定的难点。nanobind对std::unique_ptr和std::shared_ptr有很好的支持。#include nanobind/nanobind.h #include nanobind/stl/unique_ptr.h #include nanobind/stl/shared_ptr.h #include memory namespace nb nanobind; class Resource { public: Resource(int id) : id(id) { std::cout Resource id created.\n; } ~Resource() { std::cout Resource id destroyed.\n; } int getId() const { return id; } private: int id; }; // 工厂函数返回unique_ptr std::unique_ptrResource create_unique_resource(int id) { return std::make_uniqueResource(id); } // 接受shared_ptr作为参数的函数 void use_shared_resource(const std::shared_ptrResource res) { if (res) { std::cout Using resource id: res-getId() std::endl; } } // 返回shared_ptr的函数 std::shared_ptrResource get_shared_resource() { static auto resource std::make_sharedResource(999); return resource; } NB_MODULE(smart_ptr_demo, m) { // 绑定类时可以指定持有的智能指针类型 nb::class_Resource, std::shared_ptrResource(m, Resource) .def(nb::initint()) .def(get_id, Resource::getId); m.def(create_unique_resource, create_unique_resource); m.def(use_shared_resource, use_shared_resource); m.def(get_shared_resource, get_shared_resource); }Python端的使用非常直观import smart_ptr_demo as spd # 获取一个unique_ptr当Python对象被垃圾回收时C对象自动删除 unique_res spd.create_unique_resource(1) print(unique_res.get_id()) # 1 # unique_res 离开作用域或被del后会打印“Resource 1 destroyed.” # 获取一个shared_ptr shared_res spd.get_shared_resource() print(shared_res.get_id()) # 999 spd.use_shared_resource(shared_res) # Using resource id: 999 # 多个Python变量可以持有同一个shared_ptr引用计数会正确工作 alias shared_res del shared_res # 此时C对象不会销毁因为alias还持有引用 print(alias.get_id()) # 999 # 当alias也被删除后如果引用计数为0才会打印“Resource 999 destroyed.”核心要点当你在nb::class_中指定了智能指针类型如std::shared_ptrResourcenanobind会确保所有涉及该类对象的传递都使用该智能指针。这意味着从C返回的shared_ptr在Python端是安全的反之从Python传递给C的Resource对象也会被自动转换为shared_ptr。这彻底解决了跨语言边界的对象生命周期管理难题。5. 性能优化与底层交互nanobind的卖点是性能我们来看看如何充分利用它。5.1 缓冲区协议Buffer Protocol与NumPy集成对于数值计算在Python的NumPy数组和C的原始内存块之间进行零拷贝传递是终极性能需求。nanobind通过支持Python的缓冲区协议PEP 3118来实现这一点。#include nanobind/nanobind.h #include nanobind/ndarray.h // 关键头文件 #include algorithm namespace nb nanobind; using namespace nb::literals; // 用于使用“_a”字面量指定参数名 // 接受一个二维float数组例如NumPy数组并就地修改 void double_matrix(nb::ndarrayfloat, nb::ndim2 array) { // 获取形状、步长和原始指针 size_t rows array.shape(0); size_t cols array.shape(1); float* data array.data(); // 确保数组是C连续且可写的 if (!array.is_c_contiguous()) { throw std::runtime_error(Array must be C-contiguous); } for (size_t i 0; i rows * cols; i) { data[i] * 2.0f; } } // 从C创建并返回一个新的ndarray nb::ndarraynb::numpy, float create_zeros(int rows, int cols) { // 分配内存。注意这里的内存管理将交给Python的引用计数。 float* data new float[rows * cols](); // 值初始化为零 std::fill(data, data rows * cols, 0.0f); // 创建ndarray对象并指定当Python对象销毁时调用删除器 size_t shape[2] {static_castsize_t(rows), static_castsize_t(cols)}; size_t strides[2] {cols * sizeof(float), sizeof(float)}; // nb::ndarray的构造函数数据指针维度形状步长所有者Python capsule数据类型 nb::capsule owner(data, [](void* p) noexcept { delete[] (float*)p; }); return nb::ndarraynb::numpy, float(data, 2, shape, owner); } NB_MODULE(ndarray_demo, m) { m.def(double_matrix, double_matrix, array_a); m.def(create_zeros, create_zeros, rows_a, cols_a); }在Python中你可以无缝使用NumPyimport numpy as np import ndarray_demo as nd # 创建一个NumPy数组 arr np.array([[1.0, 2.0], [3.0, 4.0]], dtypenp.float32) print(Before:, arr) nd.double_matrix(arr) # 零拷贝直接修改原数组数据 print(After:, arr) # [[2., 4.], [6., 8.]] # 从C接收一个数组 zeros nd.create_zeros(3, 4) print(zeros) print(type(zeros)) # class numpy.ndarray print(zeros.shape) # (3, 4)性能关键nb::ndarray模板的第一个参数可以是nb::numpy、nb::pytorch等以指定数组的预期来源这有助于进行更严格的检查。使用nb::ndarray进行交互避免了通过Python列表再转换成std::vector的拷贝开销对于大型数组性能差异是数量级的。5.2 线程安全与全局解释器锁GILC代码是原生线程而Python有全局解释器锁GIL。在C线程中回调Python或操作Python对象时必须手动管理GIL。#include nanobind/nanobind.h #include thread #include vector namespace nb nanobind; void heavy_computation(int iterations, nb::object callback) { // 这个函数可能在C创建的线程中被调用 // 在调用任何Python API之前必须获取GIL nb::gil_scoped_acquire acquire; // 构造时获取GIL析构时释放 for (int i 0; i iterations; i) { // 模拟计算 std::this_thread::sleep_for(std::chrono::milliseconds(10)); // 回调Python函数报告进度 callback(i); } // acquire 对象析构自动释放GIL } void run_in_parallel(int task_count, nb::object py_func) { std::vectorstd::thread threads; for (int i 0; i task_count; i) { threads.emplace_back([i, py_func]() { // 每个线程需要独立获取GIL来调用Python nb::gil_scoped_acquire acquire; py_func(i); }); } for (auto t : threads) { t.join(); } } NB_MODULE(threading_demo, m) { m.def(heavy_computation, heavy_computation, iterations_a, callback_a); m.def(run_in_parallel, run_in_parallel, task_count_a, func_a); }Python脚本import threading_demo as td import threading def progress(i): # 这个函数会在C线程中被调用 print(fThread {threading.get_ident()}: Iteration {i}) print(Main thread:, threading.get_ident()) td.heavy_computation(5, progress) def task_func(task_id): print(fParallel task {task_id} in thread {threading.get_ident()}) td.run_in_parallel(4, task_func)重要警告忘记获取GIL就在非主线程中操作Python对象是导致Python解释器崩溃的最常见原因之一。nb::gil_scoped_acquire是你的安全护栏。同样如果一段C代码长时间运行且不调用Python应该在开始处使用nb::gil_scoped_release临时释放GIL让其他Python线程得以运行。6. 构建、打包与分发实战写好了绑定代码如何把它变成一个可以方便分发的Python包现代Python生态主要使用pip和setuptools。6.1 使用 pyproject.toml 和 setuptools这是目前最推荐的方式。你需要一个pyproject.toml文件和一个setup.py或setup.cfg。目录结构my_extension/ ├── pyproject.toml ├── setup.py ├── my_extension/ │ ├── __init__.py │ └── core.cpp (你的绑定代码) └── CMakeLists.txtpyproject.toml:[build-system] requires [setuptools61.0, wheel, scikit-build-core0.5] build-backend setuptools.build_metasetup.py:from setuptools import setup, Extension from setuptools.command.build_ext import build_ext import subprocess import os # 自定义构建扩展类用于调用CMake class CMakeExtension(Extension): def __init__(self, name): super().__init__(name, sources[]) class CMakeBuild(build_ext): def run(self): for ext in self.extensions: self.build_extension(ext) def build_extension(self, ext): extdir os.path.abspath(os.path.dirname(self.get_ext_fullpath(ext.name))) cmake_args [ f-DCMAKE_LIBRARY_OUTPUT_DIRECTORY{extdir}, f-DPYTHON_EXECUTABLE{sys.executable}, -DCMAKE_BUILD_TYPERelease ] build_args [--config, Release] # 支持多核编译 import multiprocessing build_args [--, f-j{multiprocessing.cpu_count()}] # 创建构建目录 build_temp os.path.join(self.build_temp, ext.name) os.makedirs(build_temp, exist_okTrue) subprocess.run([cmake, -S, ., -B, build_temp] cmake_args, checkTrue) subprocess.run([cmake, --build, build_temp] build_args, checkTrue) setup( namemy_extension, version0.1.0, ext_modules[CMakeExtension(my_extension)], cmdclass{build_ext: CMakeBuild}, zip_safeFalse, )CMakeLists.txt(项目根目录):cmake_minimum_required(VERSION 3.16) project(my_extension LANGUAGES CXX) # 查找Python和nanobind find_package(Python 3.8 REQUIRED COMPONENTS Development.Module) include(FetchContent) FetchContent_Declare(nanobind GIT_REPOSITORY https://github.com/wjakob/nanobind.git GIT_TAG v2.0.0) FetchContent_MakeAvailable(nanobind) # 添加你的扩展模块 add_library(my_extension MODULE my_extension/core.cpp) target_link_libraries(my_extension nanobind) set_target_properties(my_extension PROPERTIES CXX_VISIBILITY_PRESET hidden VISIBILITY_INLINES_HIDDEN ON PREFIX SUFFIX .so # Linux/MacWindows上为“.pyd” )配置好后在项目根目录执行pip install .setuptools会自动调用CMake完成编译和安装。6.2 使用 scikit-build-core (更现代的方式)scikit-build-core是一个更精简、基于pyproject.toml的构建后端它直接集成了CMake。pyproject.toml:[build-system] requires [scikit-build-core0.5] build-backend scikit_build_core.build [project] name my_extension version 0.1.0 [tool.scikit-build] cmake.args [-DCMAKE_BUILD_TYPERelease]无需setup.py。你的CMakeLists.txt和之前一样。然后直接运行pip install .即可。这种方式更加简洁是未来的趋势。打包避坑指南ABI兼容性在Linux上编译扩展的Python版本、编译器版本和GLIBC版本必须与运行环境匹配。使用manylinuxDocker镜像如manylinux2014_x86_64进行构建可以保证广泛的兼容性。RPATH问题在MacOS上编译出的.so文件可能有绝对路径的依赖。在CMake中设置set(CMAKE_INSTALL_RPATH loader_path)可以缓解。调试符号在开发时使用-DCMAKE_BUILD_TYPEDebug并确保链接了Python的调试库这样可以在C代码中设置断点。版本锁定在FetchContent_Declare中指定nanobind的具体版本标签如v2.0.0避免因主分支更新导致构建失败。7. 常见问题排查与调试技巧即使按照指南操作也难免会遇到问题。这里记录了一些我踩过的坑和解决方法。7.1 编译错误排查表错误信息可能原因解决方案fatal error: nanobind/nanobind.h file not found头文件路径未包含。确保CMake正确引入了nanobind并且target_link_libraries你的目标链接到了nanobind。undefined symbol: _PyArg_ParseStackPython版本不匹配或链接了错误的Python库。检查find_package(Python)找到的版本是否与你当前使用的Python环境一致。在虚拟环境中构建时尤其要注意。error: static assertion failed: ... is not a class/struct/union尝试绑定的类型不是完整的类类型。确保在绑定该类之前其定义是完整的即已经看到了类的全部内容。通常需要将绑定代码放在类定义的头文件之后。模块导入时ImportError: dynamic module does not define module export function模块初始化函数名不匹配。NB_MODULE(module_name, m)中的module_name必须与add_library的目标名以及Python中import的名字完全一致。运行时TypeError: No to_python (by-value) converter found for C type: ...尝试返回或传递了一个nanobind不认识的C类型。为该类型编写自定义的类型转换器或者将其改为使用智能指针持有如果适用。更常见的是忘记包含对应STL容器的头文件如#include nanobind/stl/vector.h。7.2 调试技巧在C中打印调试信息在绑定代码中使用std::cout或printf。输出会显示在Python运行的标准输出/错误流中。这对于跟踪函数调用顺序和参数值非常有用。使用Python的inspect模块导入模块后使用inspect.signature()查看绑定函数的签名确保参数名和类型符合预期。启用Python的faulthandler当解释器因非法内存访问而崩溃时faulthandler可以打印出崩溃时的Python堆栈。在程序开头import faulthandler; faulthandler.enable()。在CMake中开启详细编译输出在CMake配置时加上-DCMAKE_VERBOSE_MAKEFILE:BOOLON或者在构建时使用make VERBOSE1或cmake --build . --verbose可以查看完整的编译和链接命令有助于发现链接库缺失等问题。隔离测试创建一个最小的、只包含问题功能的.cpp文件进行绑定测试排除项目中其他代码的干扰。7.3 性能分析如果你怀疑绑定层本身成了性能瓶颈通常不会但大型对象频繁传递时可能使用Python的cProfile模块分析函数调用开销。对于特定的C函数可以在其前后使用Python的time.perf_counter_ns()进行纳秒级计时。考虑是否过度使用了“按值返回”。对于大型对象使用nb::rv_policy::reference_internal或返回智能指针可能更高效但要注意生命周期管理。最后切换到nanobind本身就是一次显著的性能提升尤其是开发体验上的提升。它让“编译-测试”的循环快得多使得基于C扩展的Python项目开发变得更加流畅愉快。从我个人的项目经验来看除非你需要pybind11某些极其小众的特性否则nanobind在性能、编译速度和代码简洁性上的综合优势是决定性的。
