Windows下pybind11编译C++模块后Python导入DLL失败求助

环境信息 #

• 操作系统：Windows 10
• 工具链：G++ 编译器 + VS Code
• Python版本：3.12.4
• pybind11位置：C:\Users\User\AppData\Local\Programs\Python\Python312\Lib\site-packages\pybind11

C++代码（src/test.cpp） #

#include <pybind11/pybind11.h>

int add(int i, int j) {
    return i + j;
}

namespace py = pybind11;

PYBIND11_MODULE(cmake_module, m) {
    m.def("add", &add, R"pbdoc(
        Add two numbers

        Some other explanation about the add function.
    )pbdoc");
};

CMake脚本（CMakeLists.txt） #

cmake_minimum_required(VERSION 3.30.2)
set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_FLAGS "-Wall -Wextra -pedantic -shared")
set(CMAKE_CXX_FLAGS_DEBUG "-Werror -Og")

# Specify the path to pybind11 if it's not installed globally
set(PYBIND11_DIR "C:\\Users\\User\\AppData\\Local\\Programs\\Python\\Python312\\Lib\\site-packages\\pybind11")

# Specify the path to the Python interpreter
set(PYBIND11_FINDPYTHON "C:\\Users\\User\\AppData\\Local\\Programs\\Python\\Python312\\python.exe")

# Find pybind11
find_package(pybind11 REQUIRED PATHS ${PYBIND11_DIR})

# Find Python components
find_package(Python COMPONENTS Interpreter Development REQUIRED)

# Include directories for Python headers
include_directories(${Python_INCLUDE_DIRS})

# Create the module
set(MODULE_NAME cmake_example)
pybind11_add_module(${MODULE_NAME} src/test.cpp)

问题现象 #

编译成功后在build目录生成cmake_example.cp312-win_amd64.pyd，但执行import cmake_example时报错：

ImportError: DLL load failed while importing cmake_example: The specified module could not be found.

已尝试的解决方法 #

• 在CMake中指定Python解释器路径
• 调用os.add_dll_directory("path/to/build/dir")添加DLL路径
• 将.pyd文件移动到C:\Users\User\AppData\Local\Programs\Python\Python312\DLLs目录

解决方案 #

1. 检查依赖DLL是否缺失 #

用VS工具链自带的dumpbin工具查看.pyd文件的依赖项：

dumpbin /dependents cmake_example.cp312-win_amd64.pyd

重点排查是否存在未找到的DLL，比如G++运行时库（libstdc++-6.dll、libgcc_s_seh-1.dll等）或Python相关依赖。

2. 解决G++运行时库依赖问题 #

• 若使用MinGW-w64，将MinGW的bin目录（如C:\MinGW\bin）添加到系统PATH环境变量；
• 或在CMake中添加静态编译选项，把运行时库打包进.pyd文件：

  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -static-libstdc++ -static-libgcc")
  

3. 修正CMake配置错误 #

• 替换错误的PYBIND11_FINDPYTHON变量，改用Python_EXECUTABLE指定Python解释器：

  set(Python_EXECUTABLE "C:\\Users\\User\\AppData\\Local\\Programs\\Python\\Python312\\python.exe")
  

• 移除手动添加的include_directories(${Python_INCLUDE_DIRS})，pybind11_add_module会自动处理Python头文件和链接；
• 删除手动设置的-shared参数，pybind11_add_module已默认添加共享库编译选项，重复添加可能导致冲突。

修正后的CMake脚本示例：

cmake_minimum_required(VERSION 3.30.2)
set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_FLAGS "-Wall -Wextra -pedantic")
set(CMAKE_CXX_FLAGS_DEBUG "-Werror -Og")
# 添加静态链接选项避免运行时DLL缺失
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -static-libstdc++ -static-libgcc")

# 指定Python解释器路径
set(Python_EXECUTABLE "C:\\Users\\User\\AppData\\Local\\Programs\\Python\\Python312\\python.exe")

# 查找pybind11和Python
find_package(pybind11 REQUIRED PATHS "C:\\Users\\User\\AppData\\Local\\Programs\\Python\\Python312\\Lib\\site-packages\\pybind11")
find_package(Python COMPONENTS Interpreter Development REQUIRED)

# 创建模块
set(MODULE_NAME cmake_example)
pybind11_add_module(${MODULE_NAME} src/test.cpp)

4. 验证模块导入 #

• 在build目录下直接启动Python终端执行导入；
• 或把build目录添加到PYTHONPATH环境变量后再导入模块。

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