使用venv虚拟环境时pybind11构建的Python模块无法导入问题排查

1. 模块文件名与虚拟环境Python版本不匹配 #

你手动指定的输出文件名example.cpython-310-x86_64-linux-gnu.so对应Python 3.10，如果虚拟环境使用的是其他版本（如3.9/3.11），Python会因为版本后缀不匹配无法识别模块。

解决方式：

• 先确认虚拟环境的Python版本：

  python --version
  

• 改用自动生成匹配后缀的命令构建，无需手动指定版本：

  c++ -O3 -Wall -shared -std=c++11 -fPIC $(python -m pybind11 --includes) main.cpp -o example$(python3-config --extension-suffix)
  

  该命令会通过python3-config --extension-suffix获取当前虚拟环境对应的正确后缀，生成的文件名会自动适配版本（比如Python 3.9会生成example.cpython-39-x86_64-linux-gnu.so）。

2. 模块所在目录不在Python搜索路径中 #

虽然Python默认将当前工作目录加入sys.path，但如果虚拟环境修改过PYTHONPATH变量，或者你在其他目录运行Python，就会找不到模块。

解决方式：

• 运行Python时检查当前目录是否在搜索路径内：

  import sys
  print(sys.path)
  

• 若不在，手动添加模块所在目录：

  import sys
  sys.path.append("/你的模块所在目录绝对路径")
  import example
  

• 或者将模块直接复制到虚拟环境的site-packages目录，让Python自动识别：

  cp example$(python3-config --extension-suffix) $(python -c "import site; print(site.getsitepackages()[0])")
  

3. 虚拟环境未安装pybind11 #

如果pybind11仅安装在全局Python环境，虚拟环境中缺失该依赖，即使编译成功，也可能导致模块无法正常加载。

解决方式：
激活虚拟环境后安装pybind11：

pip install pybind11

4. 编译时链接了全局Python库 #

激活虚拟环境后，python命令虽指向虚拟环境，但编译器可能意外链接到全局Python库，导致模块与虚拟环境Python不兼容。

解决方式：
编译时明确指定虚拟环境的Python头文件和库路径：

c++ -O3 -Wall -shared -std=c++11 -fPIC \
  -I$(python -c "import sysconfig; print(sysconfig.get_path('include'))") \
  -L$(python -c "import sysconfig; print(sysconfig.get_path('platlib'))")/../ \
  -lpython$(python -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')") \
  main.cpp -o example$(python3-config --extension-suffix)

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