导入pybind11模块报‘symbol not found in flat namespace’错误如何解决？

我用C++编写了几个类，希望通过pybind11打包成Python模块。在Python3.8.9虚拟环境下完成构建和安装后，导入模块时出现以下错误：

ImportError: dlopen(/Users/$USER/dictionary/py_test/venv/lib/python3.8/site-packages/MODULE.cpython-38-darwin.so, 0x0002): symbol not found in flat namespace '_PyCMethod_New'

怀疑是CMake配置问题，附上我的CMakeLists.txt文件：

cmake_minimum_required(VERSION 3.4...3.18)
SET (CMAKE_C_COMPILER "/Library/Developer/CommandLineTools/usr/bin/clang")
set (PYBIND11_PYTHON_VERSION "3.8")
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_FLAGS "-Wall -Wextra -fPIC")
project(MODULE)
set(CMAKE_OSX_ARCHITECTURES "arm64")

include_directories("/Users/$USER/dictionary/pybind11/include",
                    "/Users/$USER/opt/anaconda3/pkgs/python-3.9.12-hdfd78df_0/include/python3.9",
                    "/Users/$USER/dictionary/includes")

add_library(LIB_NAME STATIC src/BINDER_FILE.cpp)
set_target_properties(LIB_NAME PROPERTIES POSITION_INDEPENDENT_CODE ON)

add_subdirectory(pybind11)
pybind11_add_module(MODULE src/BINDER_FILE.cpp)
target_link_libraries(MODULE PRIVATE LIB_NAME)

终端执行的命令如下：

mkdir build
cd build
cmake ..
make LIB_NAME
make MODULE
cd ../
python3 setup.py bdist_wheel

设备为M1芯片MacBook。

核心问题分析 #

_PyCMethod_New符号找不到的根本原因是Python版本不匹配：你指定pybind11使用Python3.8，但手动添加的include目录却是Anaconda的Python3.9头文件，导致编译时用了3.9的API，而运行环境是3.8，出现符号缺失。此外M1芯片的架构适配细节也需要注意。

具体修复步骤 #

1. 修正Python头文件引用
   移除include_directories中的Python3.9路径，改用虚拟环境的Python3.8头文件，或者更推荐让pybind11自动检测当前环境的Python版本，无需手动指定include路径。

2. 调整CMake配置
   修改后的CMakeLists.txt示例：

   cmake_minimum_required(VERSION 3.4...3.18)
   SET (CMAKE_C_COMPILER "/Library/Developer/CommandLineTools/usr/bin/clang")
   set(CMAKE_CXX_STANDARD 20)
   set(CMAKE_CXX_FLAGS "-Wall -Wextra -fPIC")
   project(MODULE)
   set(CMAKE_OSX_ARCHITECTURES "arm64")
   
   # 让pybind11自动关联当前虚拟环境的Python3.8
   find_package(Python3 3.8 REQUIRED COMPONENTS Interpreter Development)
   include_directories("/Users/$USER/dictionary/pybind11/include",
                       "/Users/$USER/dictionary/includes")
   
   add_library(LIB_NAME STATIC src/BINDER_FILE.cpp)
   set_target_properties(LIB_NAME PROPERTIES POSITION_INDEPENDENT_CODE ON)
   
   add_subdirectory(pybind11)
   pybind11_add_module(MODULE src/BINDER_FILE.cpp)
   target_link_libraries(MODULE PRIVATE LIB_NAME)
   # 确保链接到正确的Python库
   target_link_libraries(MODULE PRIVATE Python3::Python)
   

3. 简化构建流程
   无需单独编译LIB_NAME，直接执行：

   rm -rf build
   mkdir build && cd build
   cmake ..
   make
   

   之后可直接安装模块到虚拟环境：

   make install
   

   也可跳过setup.py，直接用cmake生成的模块文件测试。

4. 验证环境一致性
   执行cmake和make前，确保终端已激活Python3.8.9的虚拟环境，让pybind11能正确检测到对应版本的Python。

额外注意事项 #

• M1芯片上，确保所有依赖（包括pybind11）均为arm64架构编译，避免x86_64架构的二进制冲突。
• 不要混合使用系统Python、Anaconda Python和虚拟环境Python，保持构建与运行环境的Python版本完全一致。

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