使用pybind11生成的.so文件在Python中导入的问题咨询

一、CLion标记import libtest为错误的修复 #

CLion的Python静态检查不会自动识别CPython格式的.so模块，按下面两种方法解决：

• 方法1：添加模块路径到解释器配置
  1. 打开File > Settings > Project: [你的项目名] > Python Interpreter
  2. 点击右侧齿轮图标，选择Show All，选中你的Python解释器
  3. 点击Show paths for the selected interpreter，再点+号添加.so文件所在目录，保存后IDE就能识别这个模块了。
• 方法2：添加类型存根文件（可选，获得代码提示）
  在.so同目录下创建libtest.pyi文件，写入函数的类型声明：

  def hello() -> str:
      """输出问候语的函数"""
  

  这样CLion不仅不会报错，还能提供函数补全提示。

二、脱离同目录导入.so的方法 #

$PATH是系统查找可执行文件的路径，Python模块的搜索依赖sys.path，所以得修改这个路径：

• 临时方案（仅当前脚本生效）
  在导入前把.so所在目录加到sys.path：

  import sys
  sys.path.append("/绝对路径/到/so文件目录")
  import libtest
  libtest.hello()
  

• 永久方案（全局生效）
  1. 把.so直接放到Python的site-packages目录，用python -c "import site; print(site.getsitepackages())"查看具体路径，复制过去后任何脚本都能直接导入。
  2. 设置PYTHONPATH环境变量：在你的shell配置文件（比如_/.bashrc、/.zshrc）里添加一行：

     export PYTHONPATH="/so文件所在目录:$PYTHONPATH"
     

     重启终端后，Python会自动搜索这个目录里的模块。

三、打包.so供他人使用 #

用setuptools+wheel打包最方便，用户直接通过pip安装就能使用：

1. 整理项目结构：

   my_libtest_package/
   ├── setup.py
   └── libtest.cpython-311-x86_64-linux-gnu.so
   

2. 编写setup.py：

   from setuptools import setup
   
   setup(
       name="libtest",
       version="0.1.0",
       package_data={
           "": ["*.so"],
       },
       include_package_data=True,
   )
   

3. 生成wheel包（更规范的分发格式）：
   • 先安装wheel工具：pip install wheel
   • 执行python setup.py bdist_wheel，会在dist/目录下生成带平台标签的wheel文件，比如libtest-0.1.0-cp311-cp311-linux_x86_64.whl
   • 把这个wheel文件发给他人，对方执行pip install libtest-0.1.0-cp311-cp311-linux_x86_64.whl就能直接使用，Python会自动把模块放到site-packages目录。

如果要支持多平台，需要在对应平台分别构建.so文件，生成对应平台的wheel包，用户根据自己的系统下载安装即可。

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