Windows下CMake构建pybind11模块遇DLL加载失败问题求助

我尝试在Windows系统上使用CMake构建pybind11模块，相关代码如下：

C++代码 #

#include <iostream>
#include <pybind11/pybind11.h>

void say_hello(){
    std::cout << "Hello, from c++!\n";
}

PYBIND11_MODULE(example, m) {
    m.def("say_hello", &say_hello);
}

CMake配置 #

cmake_minimum_required(VERSION 3.10.0)
project(example VERSION 0.1.0 LANGUAGES C CXX)

find_package(Python COMPONENTS Interpreter Development REQUIRED)
find_package(pybind11 REQUIRED)

pybind11_add_module(example example.cpp)

使用dumpbin查看依赖结果：

Dump of file build\example.cp311-win_amd64.pyd

File Type: DLL

  Image has the following dependencies:

    libgcc_s_seh-1.dll
    KERNEL32.dll
    msvcrt.dll
    libstdc++-6.dll
    python311.dll

执行Python代码时出现报错：

import example
example.say_hello()

ImportError: DLL load failed while importing example

该模块在Linux系统上运行完全正常，请问我哪里操作有误？若存在解决方案，如何保证该模块在其他系统上也能可靠运行？

问题根源 #

你的Pyd模块依赖libgcc_s_seh-1.dll和libstdc++-6.dll——这两个是MinGW/GCC的动态链接库，但Windows系统默认不自带这些文件，Python进程加载模块时找不到它们，就会抛出导入错误。Linux上正常是因为系统通常预装了GCC的运行时库。

修复步骤 #

1. 静态链接GCC运行时库 #

修改CMake配置，强制静态链接GCC的标准库，消除外部DLL依赖：

cmake_minimum_required(VERSION 3.10.0)
project(example VERSION 0.1.0 LANGUAGES C CXX)

find_package(Python COMPONENTS Interpreter Development REQUIRED)
find_package(pybind11 REQUIRED)

pybind11_add_module(example example.cpp)

# 针对MinGW/GCC添加静态链接选项
if(MINGW)
    target_link_options(example PRIVATE -static-libgcc -static-libstdc++)
endif()

重新构建后，用dumpbin检查依赖，libgcc_s_seh-1.dll和libstdc++-6.dll这两项会消失。

2. 手动部署依赖库（不推荐） #

如果必须用动态链接，可以把libgcc_s_seh-1.dll和libstdc++-6.dll从MinGW的bin目录复制到Pyd文件同目录下。但这种方式容易因版本不匹配引发问题，不建议用于分发。

跨平台可靠运行的保障措施 #

• 统一构建工具链：
  • Windows优先用MSVC而非MinGW，MSVC的运行时库（如vcruntime140.dll）在较新Windows系统默认预装，旧系统可通过打包VC Redistributable解决。CMake中指定MSVC编译器即可切换工具链。
  • Linux用系统默认GCC，构建时确保静态链接核心依赖，或依赖系统预装的标准库。
• 静态链接核心依赖：
  对pybind11和C++标准库优先选择静态链接，减少外部依赖。CMake中可通过设置PYBIND11_STATIC强制静态链接pybind11：

  set(PYBIND11_STATIC ON)
  find_package(pybind11 REQUIRED)
  

• 标准化打包分发：
  • 用setuptools配合pybind11.setup_helpers替代纯CMake，自动处理依赖和打包逻辑，生成Wheel包，跨平台兼容性更好。
  • Windows下用cpack生成安装包，包含必要运行时库；Linux下用dpkg/rpm打包，或用auditwheel处理Wheel包的系统依赖。
• 多环境测试验证：
  在目标系统（如不同版本Windows、Linux发行版）上测试模块导入和运行，提前发现依赖缺失或版本兼容问题。

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