pybind11 官方文档体系导航与快速上手从 docs/index.rst 读懂完整技术地图【免费下载链接】pybind11Seamless operability between C11 and Python项目地址: https://gitcode.com/GitHub_Trending/py/pybind11docs/index.rst是 pybind11 文档站Sphinx 构建的唯一入口页面master document它通过toctree指令把安装、入门教程、类绑定、构建系统、进阶主题、FAQ 与基准测试等二十余个文档页面组织成一份完整的学习路线图并在构建时把仓库根目录的README.rst一并引入。本文以该文档为骨架逐层拆解 pybind11 文档的目录结构与每个章节的实战价值并同步给出从安装、编译到首个扩展模块的完整操作路径帮助你按图索骥地查阅源码、编写绑定并排查问题。一、docs/index.rst 的角色整个文档系统的“主入口”在 Sphinx 体系中master_doc指定了文档树的根页面。pybind11 的构建配置 docs/conf.py 中有两行关键设置source_suffix [.rst, .md] master_doc index这意味着构建器例如sphinx-build . _build/html会首先解析docs/index.rst再顺着其中的toctree递归编译所有被引用的文档页。docs/index.rst本身的内容组织分为三个部分README 导入通过.. include:: readme.rst把仓库根目录的 README.rst 直接嵌入首页。注意docs/readme.rst是构建期由 docs/conf.py 的prepare()钩子动态生成的临时文件构建完成后即被clean_up()删除因此index.rst中这一行在阅读源码时体现为“引入项目简介”其实际内容对应仓库根目录的 README。LaTeX 特殊分支.. only:: latex指令让 PDF 版文档在此处使用独立的 “Intro” 标题HTML 版则直接渲染 README 内容。四大toctree目录块把全部文档页面按“版本变更、基础教程、进阶主题、补充信息”四个维度组织成导航树。此外conf.py还通过breathe扩展对接 Doxygenbreathe_projects {pybind11: .build/doxygenxml/}在构建时从 include/pybind11 的头文件生成 C API 参考这正是docs/reference.rst能提供自动生成接口文档的原因。二、四大 toctree 目录块逐层解读文档地图docs/index.rst用四个toctree把全部页面分为四组理解这张导航树就等于掌握了 pybind11 的全部文档脉络。2.1 版本变更区changelog 与 upgrade.. toctree:: :maxdepth: 1 changelog upgradedocs/changelog.md完整的新特性、改进与 Bug 修复清单按版本号组织适合升级时快速扫描变化点docs/upgrade.rst升级指南聚焦“影响你升级体验”的变更。例如其中明确说明pybind11 v3.0 与 2.x 系列不保持 ABI 兼容跨扩展模块使用时建议统一用 v3.0 重新编译同时v3.0 起 CMake 默认切换到现代FindPython模块PYTHON_*变量不再影响构建应改用Python_*变量。2.2 The Basics零基础四步走.. toctree:: :caption: The Basics :maxdepth: 2 installing basics classes compiling这是从零开始使用 pybind11 的核心教程链文档解决什么问题关键要点docs/installing.rst如何获得 pybind11 源码官方推荐 submodule、PyPI、conda-forge 三种方式docs/basics.rst如何编译测试集、编写第一个绑定PYBIND11_MODULE宏、module_::def、关键字/默认参数docs/classes.rst如何绑定自定义 C 类py::class_、py::init、属性与方法、继承、虚函数docs/compiling.rst用什么构建系统打包CMake、setuptools、meson-python、scikit-build-core2.3 Advanced Topics九个进阶专题.. toctree:: :caption: Advanced Topics :maxdepth: 2 advanced/functions advanced/classes advanced/exceptions advanced/smart_ptrs advanced/cast/index advanced/pycpp/index advanced/embedding advanced/misc advanced/deprecateddocs/advanced/functions.rst函数级进阶——重载、lambda、回调std::function、GIL 释放py::call_guard、keep_alive等调用策略docs/advanced/classes.rst类级进阶——虚函数与 Python 继承trampoline、运算符重载、多继承、pickle 支持docs/advanced/exceptions.rstC 异常与 Python 异常之间的转换、自定义异常类型注册docs/advanced/smart_ptrs.rststd::shared_ptr/std::unique_ptr等智能指针与引用计数语义、py::smart_holderdocs/advanced/cast/index.rst类型转换专题含 overview.rst内置转换表、stl.rst、chrono.rst、eigen.rst、functional.rst、strings.rst、custom.rst自定义 type_casterdocs/advanced/pycpp/index.rstPython 对象在 C 侧的使用含 object.rstpy::object家族、numpy.rst、utilities.rstdocs/advanced/embedding.rst反向场景——在 C 程序中内嵌并驱动 Python 解释器docs/advanced/misc.rst杂项技巧如py::print、eval、全局解释器锁管理等docs/advanced/deprecated.rst已废弃 API 及其替代方案清单。2.4 Extra InformationFAQ 与参考信息.. toctree:: :caption: Extra Information :maxdepth: 1 faq benchmark limitations reference cmake/indexdocs/faq.rst高频问题诊断。例如开篇即解答最常见的“ImportError: dynamic module does not define init function”——先确认PYBIND11_MODULE中的模块名与扩展库文件名不含.so等后缀完全一致其次检查编译所用 Python 与运行时 Python 是否版本匹配docs/benchmark.rst与 Boost.Python 的基准对比说明仓库中同时提供 docs/benchmark.py 脚本用于复现测量docs/limitations.rst已知限制与注意事项避免踩坑docs/reference.rst由 Doxygen Breathe 自动生成的 C API 参考docs/cmake/index.rstCMake 集成的完整说明对应仓库 tools/pybind11Tools.cmake、tools/pybind11Common.cmake 与 tools/pybind11NewTools.cmake 等模块的实现。三、项目定位index 文档引入的 README 核心事实由于docs/index.rst在构建期嵌入 README.rst首页承载了项目最核心的事实性描述pybind11 是轻量级 header-only 库无需链接任何额外库也无中间魔法翻译步骤核心头文件仅约 4K 行依赖 CPython 3.9、PyPy 或 GraalPy 以及 C 标准库设计目标借助 C11 的元组、lambda 与变参模板等特性在编译期自动推断类型信息从而把传统扩展模块中的大量样板代码压缩到最少语法与目标借鉴 Boost.Python但底层实现完全不同且依赖链大幅精简核心特性覆盖按值/引用/指针传参的自定义数据结构、实例方法与静态方法、函数重载、实例属性与静态属性、任意异常类型、枚举、回调、迭代器与 range、自定义运算符、单继承与多继承、STL 容器、std::shared_ptr等引用计数智能指针、可在 Python 中继承扩展的 C 类含纯虚方法、以及内建 NumPy 支持README 注明 NumPy 2 需要 pybind11 2.12额外便利Goodies支持绑定带捕获变量的 C11 lambda、尽可能利用移动语义、通过 buffer protocol 零拷贝对接 Eigen 与 NumPy、函数自动向量化、几行代码实现 Python 切片式访问、constexpr预计算函数签名以缩小二进制体积、以及类型可 pickle 化等。README 还引用了 PyRosetta 转换项目的报告相比等效的 Boost.Python 绑定二进制体积缩小约 5.4 倍、编译时间减少约 5.8 倍并在 README 中注明该数字来自该项目的外部报告可作为背景参考实际收益因项目而异。四、快速上手路线从安装到第一个扩展模块4.1 四种官方推荐安装方式根据 docs/installing.rst官方推荐以下三种方式获取 pybind11# 方式一作为 Git submodule项目中使用 -b stable 跟踪稳定分支 git submodule add -b stable ../../pybind/pybind11 extern/pybind11 git submodule update --init # 方式二PyPI不污染系统环境适合虚拟环境或 pyproject.toml pip install pybind11 # 方式三conda-forge conda install -c conda-forge pybind11另外还支持 vcpkgvcpkg install pybind11与 Homebrew/Linuxbrewbrew install pybind11。若用pip install pybind11[global]则会向/usr/local/include/pybind11与/usr/local/share/cmake/pybind11写入全局文件README 与安装文档都提示除非使用虚拟环境或明确需要全局可见否则不建议对系统 Python 执行该安装。安装后pybind11 提供了命令行工具支持可一键输出编译所需参数实现见 pybind11/commands.py 与 pybind11/main.pypython3 -m pybind11 --includes python3 -m pybind11 --extension-suffix4.2 编译并运行仓库自带测试集按 docs/basics.rst先搭建测试环境并运行官方测试集覆盖 pybind11 全部特性Linux/macOS需安装python-dev或python3-dev与cmakemacOS 自带 Python 开箱即用但 cmake 仍需安装mkdir build cd build cmake .. make check -j 4make check会同时完成编译与测试运行。仓库根目录的 CMakeLists.txt 与 tests/CMakeLists.txt 定义了这些测试目标的构建规则。Windows仅支持 Visual Studio 2019 及更新版本官方建议开启/permissive-标志以强制标准一致性非必需但推荐。命令行操作如下mkdir build cd build cmake .. cmake --build . --config Release --target check若测试全部失败先检查 Python 二进制与测试程序是否为相同处理器类型与位宽i386 或 x86_64可通过cmake -A x64 ..为生成的 Visual Studio 工程显式指定 x86_64 架构。4.3 第一个绑定示例暴露一个加法函数bocs/basics.rst 用一个极简例子演示完整流程。创建example.cpp#include pybind11/pybind11.h namespace py pybind11; int add(int i, int j) { return i j; } PYBIND11_MODULE(example, m, py::mod_gil_not_used()) { m.doc() pybind11 example plugin; // optional module docstring m.def(add, add, A function that adds two numbers); }要点说明#include pybind11/pybind11.h会间接包含Python.h因此它必须是任何源文件或头文件中第一个被包含的头文件与直接包含Python.h的注意事项相同PYBIND11_MODULE(example, m, ...)宏生成一个 Pythonimport时被调用的入口函数第一个参数是模块名不加引号第二个参数m是py::module_类型的绑定接口对象m.def()负责生成把 C 函数暴露给 Python 的绑定代码函数参数与返回值的类型信息全部由模板元编程在编译期自动推断这正是 pybind11 大幅减少样板代码的核心机制宏的第三个参数py::mod_gil_not_used()属于 v3 新增的模块选项。手动编译Linuxc -O3 -Wall -shared -stdc11 -fPIC \ $(python3 -m pybind11 --includes) \ example.cpp -o example$(python3 -m pybind11 --extension-suffix)提示若你通过 submodule 方式extern/pybind11获取源码则用$(python3-config --includes) -Iextern/pybind11/include替换$(python3 -m pybind11 --includes)完整跨平台编译方案见 docs/compiling.rst。随后在 Python 中直接使用 import example example.add(1, 2) 3仓库的 tests/test_modules.cpp 与 tests/test_modules.py 提供了模块级绑定的完整测试用例可作进阶参考。4.4 使用 CMake / pyproject.toml 构建对已有 C 工程推荐 docs/compiling.rst 中的 CMake 方案函数pybind11_add_module自动处理各平台扩展模块构建细节cmake_minimum_required(VERSION 3.15...4.2) project(example LANGUAGES CXX) set(PYBIND11_FINDPYTHON ON) find_package(pybind11 CONFIG REQUIRED) pybind11_add_module(example example.cpp) install(TARGETS example DESTINATION .)配合现代打包工具pip / build / cibuildwheel / uv只需一个pyproject.toml[build-system] requires [scikit-build-core, pybind11] build-backend scikit_build_core.build [project] name example version 0.1.0五、核心绑定技巧速览basics 章节精华5.1 关键字参数通过py::arg标签向 Python 暴露参数名m.def(add, add, A function which adds two numbers, py::arg(i), py::arg(j));此后既可按位置调用example.add(1, 2)也可用关键字调用example.add(i1, j2)且参数名会出现在help(example)的函数签名中Signature : (i: int, j: int) - int。py::arg还提供 C11 字面量简写需先声明using namespace pybind11::literals;该声明只会引入字面量、不会引入pybind11命名空间的其他内容m.def(add1, add, py::arg(i), py::arg(j)); // 常规写法 m.def(add2, add, i_a, j_a); // 简写5.2 默认参数pybind11 无法从函数类型信息中自动提取 C 默认值必须显式声明int add(int i 1, int j 2) { return i j; } m.def(add, add, A function which adds two numbers, py::arg(i) 1, py::arg(j) 2); // 简写m.def(add2, add, i_a 1, j_a 2);默认值同样会反映到文档签名中Signature : (i: int 1, j: int 2) - int。仓库 tests/test_kwargs_and_defaults.cpp 与 tests/test_kwargs_and_defaults.py 覆盖了关键字参数与默认参数的各种组合与边界情形。5.3 导出变量用attr把 C 侧的值注册为模块属性内置类型与一般对象赋值时自动转换也可用py::cast显式转换PYBIND11_MODULE(example, m, py::mod_gil_not_used()) { m.attr(the_answer) 42; py::object world py::cast(World); m.attr(what) world; }Python 侧访问 import example example.the_answer 42 example.what World5.4 绑定自定义类cocs/classes.rst 以Pet结构体为例展示类绑定用py::class_Pet(m, Pet)声明绑定.def(py::initconst std::string ())绑定构造函数.def(setName, Pet::setName)等绑定成员方法。文档特别提示自 pybind11 v3 起多数场景推荐引入py::smart_holder以获得更安全的持有语义详见 advanced 章节并建议避免绑定位于匿名命名空间中的 C 类型跨平台兼容性风险见 tests/test_unnamed_namespace_a.py 中的 XFAIL 条件说明。5.5 内置类型转换advanced/cast/overview.rst 总结了三种类型交互模式C 原生类型 Python 包装层py::class_、Python 原生类型 C 包装层py::object家族如py::list只加薄包装不改语义、以及 C/Python 原生类型互转如std::vectorint与 Python list 之间基于拷贝的转换。文档强调内置转换本质是数据拷贝对小而不可变类型很合适但对大型数据结构代价高昂可用自定义包装opaque 类型机制绕开拷贝。六、从文档到源码仓库证据地图文档中描述的能力都可以在仓库中找到对应实现与测试证据文档主题核心实现测试佐证PYBIND11_MODULE宏与模块接口include/pybind11/pybind11.htests/test_modules.cpp、tests/test_modules.py关键字/默认参数标签include/pybind11/attr.htests/test_kwargs_and_defaults.cpppy::class_类绑定include/pybind11/pybind11.hclass_ 模板tests/test_class.cpp、tests/test_class.py类型转换与 type_casterinclude/pybind11/cast.htests/test_builtin_casters.cpp内置转换表所列 STL 支持include/pybind11/stl.htests/test_stl.cppCMake 集成tools/pybind11Tools.cmake、tools/pybind11Common.cmake、tools/pybind11NewTools.cmaketests/CMakeLists.txt命令行python3 -m pybind11pybind11/commands.pytests/extra_python_package/test_files.py七、阅读路线建议首次接触 pybind11按 The Basics 顺序阅读——docs/installing.rst → docs/basics.rst → docs/classes.rst → docs/compiling.rst同时运行仓库测试集make check做实测验证已有 Boost.Python 经验docs/basics.rst 建议直接跳到 tests 目录通读测试用例这些用例覆盖了 pybind11 的全部特性是最快的功能全景图需要某个具体能力按 Advanced Topics 的九个专题定位文档再到对应的实现头文件与同名测试文件test_*.cpp/test_*.py交叉阅读形成“文档 → 实现 → 测试”的闭环理解升级维护现有绑定先读 docs/upgrade.rst 了解破坏性变更如 v3.0 的 ABI 兼容性与 CMake FindPython 切换再对照 docs/changelog.md 核对细节打包发布重点阅读 docs/compiling.rst 与 docs/cmake/index.rst按需选择 CMake、setuptools 或 meson-python。综上所述docs/index.rst虽然本身只有几十行toctree指令却是整个 pybind11 知识体系的枢纽它以最小的篇幅承载了“安装 → 基础 → 进阶 → 参考”的完整学习路径并在构建期合并 README 形成首页。把这张导航树与仓库源码、测试用例对应起来即可高效地从零开始掌握这一 header-only 的 C/Python 互操作库。【免费下载链接】pybind11Seamless operability between C11 and Python项目地址: https://gitcode.com/GitHub_Trending/py/pybind11创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pybind11 官方文档体系导航与快速上手：从 docs/index.rst 读懂完整技术地图
pybind11 官方文档体系导航与快速上手从 docs/index.rst 读懂完整技术地图【免费下载链接】pybind11Seamless operability between C11 and Python项目地址: https://gitcode.com/GitHub_Trending/py/pybind11docs/index.rst是 pybind11 文档站Sphinx 构建的唯一入口页面master document它通过toctree指令把安装、入门教程、类绑定、构建系统、进阶主题、FAQ 与基准测试等二十余个文档页面组织成一份完整的学习路线图并在构建时把仓库根目录的README.rst一并引入。本文以该文档为骨架逐层拆解 pybind11 文档的目录结构与每个章节的实战价值并同步给出从安装、编译到首个扩展模块的完整操作路径帮助你按图索骥地查阅源码、编写绑定并排查问题。一、docs/index.rst 的角色整个文档系统的“主入口”在 Sphinx 体系中master_doc指定了文档树的根页面。pybind11 的构建配置 docs/conf.py 中有两行关键设置source_suffix [.rst, .md] master_doc index这意味着构建器例如sphinx-build . _build/html会首先解析docs/index.rst再顺着其中的toctree递归编译所有被引用的文档页。docs/index.rst本身的内容组织分为三个部分README 导入通过.. include:: readme.rst把仓库根目录的 README.rst 直接嵌入首页。注意docs/readme.rst是构建期由 docs/conf.py 的prepare()钩子动态生成的临时文件构建完成后即被clean_up()删除因此index.rst中这一行在阅读源码时体现为“引入项目简介”其实际内容对应仓库根目录的 README。LaTeX 特殊分支.. only:: latex指令让 PDF 版文档在此处使用独立的 “Intro” 标题HTML 版则直接渲染 README 内容。四大toctree目录块把全部文档页面按“版本变更、基础教程、进阶主题、补充信息”四个维度组织成导航树。此外conf.py还通过breathe扩展对接 Doxygenbreathe_projects {pybind11: .build/doxygenxml/}在构建时从 include/pybind11 的头文件生成 C API 参考这正是docs/reference.rst能提供自动生成接口文档的原因。二、四大 toctree 目录块逐层解读文档地图docs/index.rst用四个toctree把全部页面分为四组理解这张导航树就等于掌握了 pybind11 的全部文档脉络。2.1 版本变更区changelog 与 upgrade.. toctree:: :maxdepth: 1 changelog upgradedocs/changelog.md完整的新特性、改进与 Bug 修复清单按版本号组织适合升级时快速扫描变化点docs/upgrade.rst升级指南聚焦“影响你升级体验”的变更。例如其中明确说明pybind11 v3.0 与 2.x 系列不保持 ABI 兼容跨扩展模块使用时建议统一用 v3.0 重新编译同时v3.0 起 CMake 默认切换到现代FindPython模块PYTHON_*变量不再影响构建应改用Python_*变量。2.2 The Basics零基础四步走.. toctree:: :caption: The Basics :maxdepth: 2 installing basics classes compiling这是从零开始使用 pybind11 的核心教程链文档解决什么问题关键要点docs/installing.rst如何获得 pybind11 源码官方推荐 submodule、PyPI、conda-forge 三种方式docs/basics.rst如何编译测试集、编写第一个绑定PYBIND11_MODULE宏、module_::def、关键字/默认参数docs/classes.rst如何绑定自定义 C 类py::class_、py::init、属性与方法、继承、虚函数docs/compiling.rst用什么构建系统打包CMake、setuptools、meson-python、scikit-build-core2.3 Advanced Topics九个进阶专题.. toctree:: :caption: Advanced Topics :maxdepth: 2 advanced/functions advanced/classes advanced/exceptions advanced/smart_ptrs advanced/cast/index advanced/pycpp/index advanced/embedding advanced/misc advanced/deprecateddocs/advanced/functions.rst函数级进阶——重载、lambda、回调std::function、GIL 释放py::call_guard、keep_alive等调用策略docs/advanced/classes.rst类级进阶——虚函数与 Python 继承trampoline、运算符重载、多继承、pickle 支持docs/advanced/exceptions.rstC 异常与 Python 异常之间的转换、自定义异常类型注册docs/advanced/smart_ptrs.rststd::shared_ptr/std::unique_ptr等智能指针与引用计数语义、py::smart_holderdocs/advanced/cast/index.rst类型转换专题含 overview.rst内置转换表、stl.rst、chrono.rst、eigen.rst、functional.rst、strings.rst、custom.rst自定义 type_casterdocs/advanced/pycpp/index.rstPython 对象在 C 侧的使用含 object.rstpy::object家族、numpy.rst、utilities.rstdocs/advanced/embedding.rst反向场景——在 C 程序中内嵌并驱动 Python 解释器docs/advanced/misc.rst杂项技巧如py::print、eval、全局解释器锁管理等docs/advanced/deprecated.rst已废弃 API 及其替代方案清单。2.4 Extra InformationFAQ 与参考信息.. toctree:: :caption: Extra Information :maxdepth: 1 faq benchmark limitations reference cmake/indexdocs/faq.rst高频问题诊断。例如开篇即解答最常见的“ImportError: dynamic module does not define init function”——先确认PYBIND11_MODULE中的模块名与扩展库文件名不含.so等后缀完全一致其次检查编译所用 Python 与运行时 Python 是否版本匹配docs/benchmark.rst与 Boost.Python 的基准对比说明仓库中同时提供 docs/benchmark.py 脚本用于复现测量docs/limitations.rst已知限制与注意事项避免踩坑docs/reference.rst由 Doxygen Breathe 自动生成的 C API 参考docs/cmake/index.rstCMake 集成的完整说明对应仓库 tools/pybind11Tools.cmake、tools/pybind11Common.cmake 与 tools/pybind11NewTools.cmake 等模块的实现。三、项目定位index 文档引入的 README 核心事实由于docs/index.rst在构建期嵌入 README.rst首页承载了项目最核心的事实性描述pybind11 是轻量级 header-only 库无需链接任何额外库也无中间魔法翻译步骤核心头文件仅约 4K 行依赖 CPython 3.9、PyPy 或 GraalPy 以及 C 标准库设计目标借助 C11 的元组、lambda 与变参模板等特性在编译期自动推断类型信息从而把传统扩展模块中的大量样板代码压缩到最少语法与目标借鉴 Boost.Python但底层实现完全不同且依赖链大幅精简核心特性覆盖按值/引用/指针传参的自定义数据结构、实例方法与静态方法、函数重载、实例属性与静态属性、任意异常类型、枚举、回调、迭代器与 range、自定义运算符、单继承与多继承、STL 容器、std::shared_ptr等引用计数智能指针、可在 Python 中继承扩展的 C 类含纯虚方法、以及内建 NumPy 支持README 注明 NumPy 2 需要 pybind11 2.12额外便利Goodies支持绑定带捕获变量的 C11 lambda、尽可能利用移动语义、通过 buffer protocol 零拷贝对接 Eigen 与 NumPy、函数自动向量化、几行代码实现 Python 切片式访问、constexpr预计算函数签名以缩小二进制体积、以及类型可 pickle 化等。README 还引用了 PyRosetta 转换项目的报告相比等效的 Boost.Python 绑定二进制体积缩小约 5.4 倍、编译时间减少约 5.8 倍并在 README 中注明该数字来自该项目的外部报告可作为背景参考实际收益因项目而异。四、快速上手路线从安装到第一个扩展模块4.1 四种官方推荐安装方式根据 docs/installing.rst官方推荐以下三种方式获取 pybind11# 方式一作为 Git submodule项目中使用 -b stable 跟踪稳定分支 git submodule add -b stable ../../pybind/pybind11 extern/pybind11 git submodule update --init # 方式二PyPI不污染系统环境适合虚拟环境或 pyproject.toml pip install pybind11 # 方式三conda-forge conda install -c conda-forge pybind11另外还支持 vcpkgvcpkg install pybind11与 Homebrew/Linuxbrewbrew install pybind11。若用pip install pybind11[global]则会向/usr/local/include/pybind11与/usr/local/share/cmake/pybind11写入全局文件README 与安装文档都提示除非使用虚拟环境或明确需要全局可见否则不建议对系统 Python 执行该安装。安装后pybind11 提供了命令行工具支持可一键输出编译所需参数实现见 pybind11/commands.py 与 pybind11/main.pypython3 -m pybind11 --includes python3 -m pybind11 --extension-suffix4.2 编译并运行仓库自带测试集按 docs/basics.rst先搭建测试环境并运行官方测试集覆盖 pybind11 全部特性Linux/macOS需安装python-dev或python3-dev与cmakemacOS 自带 Python 开箱即用但 cmake 仍需安装mkdir build cd build cmake .. make check -j 4make check会同时完成编译与测试运行。仓库根目录的 CMakeLists.txt 与 tests/CMakeLists.txt 定义了这些测试目标的构建规则。Windows仅支持 Visual Studio 2019 及更新版本官方建议开启/permissive-标志以强制标准一致性非必需但推荐。命令行操作如下mkdir build cd build cmake .. cmake --build . --config Release --target check若测试全部失败先检查 Python 二进制与测试程序是否为相同处理器类型与位宽i386 或 x86_64可通过cmake -A x64 ..为生成的 Visual Studio 工程显式指定 x86_64 架构。4.3 第一个绑定示例暴露一个加法函数bocs/basics.rst 用一个极简例子演示完整流程。创建example.cpp#include pybind11/pybind11.h namespace py pybind11; int add(int i, int j) { return i j; } PYBIND11_MODULE(example, m, py::mod_gil_not_used()) { m.doc() pybind11 example plugin; // optional module docstring m.def(add, add, A function that adds two numbers); }要点说明#include pybind11/pybind11.h会间接包含Python.h因此它必须是任何源文件或头文件中第一个被包含的头文件与直接包含Python.h的注意事项相同PYBIND11_MODULE(example, m, ...)宏生成一个 Pythonimport时被调用的入口函数第一个参数是模块名不加引号第二个参数m是py::module_类型的绑定接口对象m.def()负责生成把 C 函数暴露给 Python 的绑定代码函数参数与返回值的类型信息全部由模板元编程在编译期自动推断这正是 pybind11 大幅减少样板代码的核心机制宏的第三个参数py::mod_gil_not_used()属于 v3 新增的模块选项。手动编译Linuxc -O3 -Wall -shared -stdc11 -fPIC \ $(python3 -m pybind11 --includes) \ example.cpp -o example$(python3 -m pybind11 --extension-suffix)提示若你通过 submodule 方式extern/pybind11获取源码则用$(python3-config --includes) -Iextern/pybind11/include替换$(python3 -m pybind11 --includes)完整跨平台编译方案见 docs/compiling.rst。随后在 Python 中直接使用 import example example.add(1, 2) 3仓库的 tests/test_modules.cpp 与 tests/test_modules.py 提供了模块级绑定的完整测试用例可作进阶参考。4.4 使用 CMake / pyproject.toml 构建对已有 C 工程推荐 docs/compiling.rst 中的 CMake 方案函数pybind11_add_module自动处理各平台扩展模块构建细节cmake_minimum_required(VERSION 3.15...4.2) project(example LANGUAGES CXX) set(PYBIND11_FINDPYTHON ON) find_package(pybind11 CONFIG REQUIRED) pybind11_add_module(example example.cpp) install(TARGETS example DESTINATION .)配合现代打包工具pip / build / cibuildwheel / uv只需一个pyproject.toml[build-system] requires [scikit-build-core, pybind11] build-backend scikit_build_core.build [project] name example version 0.1.0五、核心绑定技巧速览basics 章节精华5.1 关键字参数通过py::arg标签向 Python 暴露参数名m.def(add, add, A function which adds two numbers, py::arg(i), py::arg(j));此后既可按位置调用example.add(1, 2)也可用关键字调用example.add(i1, j2)且参数名会出现在help(example)的函数签名中Signature : (i: int, j: int) - int。py::arg还提供 C11 字面量简写需先声明using namespace pybind11::literals;该声明只会引入字面量、不会引入pybind11命名空间的其他内容m.def(add1, add, py::arg(i), py::arg(j)); // 常规写法 m.def(add2, add, i_a, j_a); // 简写5.2 默认参数pybind11 无法从函数类型信息中自动提取 C 默认值必须显式声明int add(int i 1, int j 2) { return i j; } m.def(add, add, A function which adds two numbers, py::arg(i) 1, py::arg(j) 2); // 简写m.def(add2, add, i_a 1, j_a 2);默认值同样会反映到文档签名中Signature : (i: int 1, j: int 2) - int。仓库 tests/test_kwargs_and_defaults.cpp 与 tests/test_kwargs_and_defaults.py 覆盖了关键字参数与默认参数的各种组合与边界情形。5.3 导出变量用attr把 C 侧的值注册为模块属性内置类型与一般对象赋值时自动转换也可用py::cast显式转换PYBIND11_MODULE(example, m, py::mod_gil_not_used()) { m.attr(the_answer) 42; py::object world py::cast(World); m.attr(what) world; }Python 侧访问 import example example.the_answer 42 example.what World5.4 绑定自定义类cocs/classes.rst 以Pet结构体为例展示类绑定用py::class_Pet(m, Pet)声明绑定.def(py::initconst std::string ())绑定构造函数.def(setName, Pet::setName)等绑定成员方法。文档特别提示自 pybind11 v3 起多数场景推荐引入py::smart_holder以获得更安全的持有语义详见 advanced 章节并建议避免绑定位于匿名命名空间中的 C 类型跨平台兼容性风险见 tests/test_unnamed_namespace_a.py 中的 XFAIL 条件说明。5.5 内置类型转换advanced/cast/overview.rst 总结了三种类型交互模式C 原生类型 Python 包装层py::class_、Python 原生类型 C 包装层py::object家族如py::list只加薄包装不改语义、以及 C/Python 原生类型互转如std::vectorint与 Python list 之间基于拷贝的转换。文档强调内置转换本质是数据拷贝对小而不可变类型很合适但对大型数据结构代价高昂可用自定义包装opaque 类型机制绕开拷贝。六、从文档到源码仓库证据地图文档中描述的能力都可以在仓库中找到对应实现与测试证据文档主题核心实现测试佐证PYBIND11_MODULE宏与模块接口include/pybind11/pybind11.htests/test_modules.cpp、tests/test_modules.py关键字/默认参数标签include/pybind11/attr.htests/test_kwargs_and_defaults.cpppy::class_类绑定include/pybind11/pybind11.hclass_ 模板tests/test_class.cpp、tests/test_class.py类型转换与 type_casterinclude/pybind11/cast.htests/test_builtin_casters.cpp内置转换表所列 STL 支持include/pybind11/stl.htests/test_stl.cppCMake 集成tools/pybind11Tools.cmake、tools/pybind11Common.cmake、tools/pybind11NewTools.cmaketests/CMakeLists.txt命令行python3 -m pybind11pybind11/commands.pytests/extra_python_package/test_files.py七、阅读路线建议首次接触 pybind11按 The Basics 顺序阅读——docs/installing.rst → docs/basics.rst → docs/classes.rst → docs/compiling.rst同时运行仓库测试集make check做实测验证已有 Boost.Python 经验docs/basics.rst 建议直接跳到 tests 目录通读测试用例这些用例覆盖了 pybind11 的全部特性是最快的功能全景图需要某个具体能力按 Advanced Topics 的九个专题定位文档再到对应的实现头文件与同名测试文件test_*.cpp/test_*.py交叉阅读形成“文档 → 实现 → 测试”的闭环理解升级维护现有绑定先读 docs/upgrade.rst 了解破坏性变更如 v3.0 的 ABI 兼容性与 CMake FindPython 切换再对照 docs/changelog.md 核对细节打包发布重点阅读 docs/compiling.rst 与 docs/cmake/index.rst按需选择 CMake、setuptools 或 meson-python。综上所述docs/index.rst虽然本身只有几十行toctree指令却是整个 pybind11 知识体系的枢纽它以最小的篇幅承载了“安装 → 基础 → 进阶 → 参考”的完整学习路径并在构建期合并 README 形成首页。把这张导航树与仓库源码、测试用例对应起来即可高效地从零开始掌握这一 header-only 的 C/Python 互操作库。【免费下载链接】pybind11Seamless operability between C11 and Python项目地址: https://gitcode.com/GitHub_Trending/py/pybind11创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考