Ubuntu20.04 Python3环境下跨文件夹导入ext.so的正确方法

针对Ubuntu 20.04 + Python3环境下跨路径通过import Ext导入ext.so的需求，核心逻辑是让Python解释器能在模块搜索路径中定位到对应的扩展文件，以下是经过验证的可落地方案，按推荐优先级排序： #

方案1：代码内注入搜索路径（最推荐，无额外环境依赖） #

在业务代码最顶部、执行import Ext之前，把ext.so所在的文件夹绝对路径加入Python的模块搜索列表即可，示例代码：

import sys
# 替换为你本地ext.so实际存放的文件夹绝对路径
EXT_LIB_DIR = "/opt/third_party/lib/ext_module"
if EXT_LIB_DIR not in sys.path:
    sys.path.append(EXT_LIB_DIR)

# 路径注入完成后正常导入
import Ext

注意：这里填入的必须是ext.so所在的父文件夹路径，不能直接写ext.so文件的完整路径。

方案2：运行时临时指定环境变量（适合临时调试，无需修改代码） #

执行脚本前在终端设置PYTHONPATH变量，把so所在目录加入搜索路径，单次生效的写法：

# 替换为实际的so存放目录
PYTHONPATH=/opt/third_party/lib/ext_module python3 your_run_script.py

如果需要当前终端会话下多次运行，可以先导出环境变量再执行脚本：

export PYTHONPATH=/opt/third_party/lib/ext_module:$PYTHONPATH
python3 your_run_script.py
python3 other_script.py

方案3：永久配置用户级环境变量（适合固定路径长期使用） #

如果ext.so的存放路径固定，希望每次打开终端都能直接导入，可以把环境变量配置写入shell的用户配置文件：

1. Ubuntu 20.04默认使用bash，直接编辑~/.bashrc，在文件末尾追加：

   export PYTHONPATH=/opt/third_party/lib/ext_module:$PYTHONPATH
   

2. 执行source ~/.bashrc让配置立即生效，后续该用户下所有Python3进程都能搜索到这个路径。

方案4：放入Python默认扩展目录（不推荐，易污染系统环境） #

可以执行以下命令查看Python3默认的第三方扩展库存放路径：

python3 -c "import sysconfig; print(sysconfig.get_path('platlib'))"

把ext.so直接移动到命令输出的目录下即可全局导入，但这种方式会修改系统Python的目录内容，容易和apt安装的Python包产生冲突，非必要不使用。 #

常见问题排查 #

• 若报「模块找不到」错误：先检查路径是否填成了文件路径而非文件夹路径，再确认so文件的权限是否对当前运行用户可读
• 若报后缀不匹配错误：执行python3 -c "import importlib.machinery; print(importlib.machinery.EXTENSION_SUFFIXES)"查看当前Python版本要求的扩展后缀，把ext.so重命名为Ext+对应后缀即可，比如Python3.8对应命名为Ext.cpython-38-x86_64-linux-gnu.so
• 若报ELF格式或符号找不到错误：说明ext.so的编译版本、CPU架构和当前Python3环境不匹配，需要用对应环境重新编译扩展

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