pybind11是一个轻量级的头文件库，能够在C++和Python之间建立高效的绑定关系，让开发者可以直接将C++编写的函数、类封装成Python模块，兼顾C++的执行效率和Python的开发便捷性。它在科学计算、高性能服务开发等场景中应用十分广泛。
环境准备
在开始配置之前，需要确保本地已经安装以下基础环境：
- Python 3.6及以上版本，并且已经配置好环境变量
- C++编译器，Windows系统推荐安装Visual Studio 2019及以上版本，Linux系统推荐GCC 7及以上版本，macOS系统推荐Xcode自带的Clang编译器
- CMake 3.12及以上版本，用于构建pybind11项目
pybind11安装方法
方法一：使用pip安装
这是最简便的安装方式，适合大多数常规使用场景，打开终端执行以下命令即可：
pip install pybind11
安装完成后可以通过以下Python代码验证是否安装成功：
import pybind11 print(pybind11.__version__)
方法二：从源码编译安装
如果需要使用最新特性或者自定义编译选项，可以选择从源码安装，步骤如下：
# 克隆pybind11源码仓库 git clone https://github.com/pybind/pybind11.git cd pybind11 # 创建构建目录 mkdir build && cd build # 执行CMake配置 cmake .. # 编译并安装 make -j4 sudo make install
基础使用示例
下面通过一个简单的示例演示如何使用pybind11将C++函数封装为Python模块。
编写C++代码
创建名为example.cpp的文件，内容如下：
#include <pybind11/pybind11.h>
// 定义一个简单的加法函数
int add(int a, int b) {
return a + b;
}
// 使用pybind11的模块定义宏
PYBIND11_MODULE(example, m) {
// 设置模块说明
m.doc() = "这是一个简单的pybind11示例模块";
// 绑定add函数到Python模块
m.def("add", &add, "两个整型数相加的函数");
}
编写CMake构建文件
创建CMakeLists.txt文件，内容如下：
cmake_minimum_required(VERSION 3.12) project(example_module) # 查找pybind11包 find_package(pybind11 REQUIRED) # 添加Python模块 pybind11_add_module(example example.cpp)
编译生成模块
在源码目录下执行以下命令完成编译：
mkdir build && cd build cmake .. make
编译完成后会在build目录下生成example.cpython-xxx.so（Linux/macOS）或者example.cp38-win_amd64.pyd（Windows）文件，这就是可以直接被Python导入的模块。
Python调用测试
将生成的模块文件复制到Python脚本同级目录，创建测试脚本test.py：
import example
result = example.add(3, 5)
print(f"3加5的结果是：{result}")
执行脚本后如果输出3加5的结果是：8，说明混合编程环境配置和使用都正常。
常见问题解决
- 编译时提示找不到pybind11头文件：检查pybind11是否正确安装，或者CMakeLists.txt中是否正确配置了pybind11的路径
- Python导入模块时提示模块格式错误：检查编译生成的模块是否和当前Python版本匹配，比如Python3.8编译的模块不能在Python3.10环境中使用
- 函数参数类型不匹配：pybind11会自动进行类型转换，但如果传入的参数类型和C++函数定义的参数类型差异过大，会导致调用失败，需要保证传入参数类型符合要求
pybind11C++_Python混合编程环境配置Python扩展修改时间：2026-07-11 04:21:19