如何将CMake构建的PyBind11模块打包为可本地pip安装的Python包

步骤1：调整项目目录结构 #

把你的C++源码和CMake配置放到src目录下，同时创建打包所需的配置文件，最终结构如下：

python_package_from_module/
├── pyproject.toml
├── setup.cfg
├── setup.py
└── src/
    ├── __init__.py
    ├── CMakeLists.txt
    ├── 你的C++源码文件（如example.cpp）
    └── 其他依赖源码

• src/__init__.py：让Python识别该目录为包，内容可直接导入生成的模块：

  from .python_module import *
  

步骤2：配置pyproject.toml #

指定构建依赖和后端工具，确保pip能获取打包所需的组件：

[build-system]
requires = ["setuptools", "wheel", "cmake", "pybind11"]
build-backend = "setuptools.build_meta"

步骤3：编写极简setup.py #

仅封装CMake构建流程，替代手动执行cmake和make的操作：

from setuptools import setup, Extension
from setuptools.command.build_ext import build_ext
import os
import sys
import subprocess

class CMakeBuild(build_ext):
    def build_extension(self, ext):
        # 创建CMake构建目录
        build_dir = os.path.join(os.path.dirname(__file__), "cmake_build")
        os.makedirs(build_dir, exist_ok=True)

        # 运行CMake配置（关联当前Python解释器）
        subprocess.check_call([
            "cmake", "../src",
            "-DCMAKE_BUILD_TYPE=Release",
            f"-DPYTHON_EXECUTABLE={sys.executable}"
        ], cwd=build_dir)

        # 执行编译
        subprocess.check_call(["make"], cwd=build_dir)

        # 将生成的.so文件复制到包目录
        ext_path = self.get_ext_fullpath(ext.name)
        os.makedirs(os.path.dirname(ext_path), exist_ok=True)
        subprocess.check_call([
            "cp",
            os.path.join(build_dir, "python_module.so"),
            ext_path
        ])

# 注册扩展模块，sources留空因为用CMake处理源码
setup(
    ext_modules=[Extension("python_package_from_module.python_module", sources=[])],
    cmdclass={"build_ext": CMakeBuild}
)

步骤4：配置setup.cfg #

填写包的元数据和安装规则：

[metadata]
name = python_package_from_module
version = 0.1.0
author = 你的名字
description = 基于CMake+PyBind11的Python扩展模块
long_description = file: README.md
long_description_content_type = text/markdown

[options]
packages = python_package_from_module
package_dir =
    python_package_from_module = src
include_package_data = True
zip_safe = False  # C扩展模块不能被压缩打包

步骤5：本地安装测试 #

在项目根目录执行以下命令完成安装：

pip install .

安装成功后，即可在任意Python环境中直接导入使用：

import python_package_from_module
# 调用模块中的函数/类，比如
python_package_from_module.your_function()

注意事项 #

• 确保CMakeLists.txt中pybind11_add_module生成的模块名是python_module，与setup.py中的配置一致
• 如果你的CMake需要额外编译参数，可在subprocess.check_call的cmake命令中添加
• 若需重新构建，可先删除cmake_build目录和build目录，再重新执行安装命令

内容的提问来源于stack exchange，提问作者Naomi