Cython编译独立可执行文件时出现自定义模块找不到错误

问题背景 #

将包含多个自定义Python文件的项目编译为独立可执行文件，以带main函数的main.py作为入口点，编译流程为：先用Cython处理所有Python文件，再用GCC编译生成二进制文件。但生成的可执行文件在源码目录能正常运行，移出目录后就抛出ModuleNotFoundError，提示找不到自定义模块common。

报错信息 #

Traceback (most recent call last):
  File "main.py", line 12, in init main
ModuleNotFoundError: No module named 'common'

环境与编译命令 #

• 环境：Ubuntu 22.04、Cython 0.29.37
• 编译命令：

  python3 -m cython -3 {py_file_string}
  python3 -m cython --embed -3 -o main.c main.py
  gcc -Os -I /usr/include/python3.10 {c_files_string} -lpython3.10 -o {output_name}
  

  其中{py_file_string}为所有Python文件列表（如common.py main.py），{c_files_string}为对应生成的C文件列表（如common.c main.c）。

解决方案：生成完全独立的二进制文件 #

方法1：将自定义模块编译为静态库并链接（推荐） #

这种方法会把所有自定义模块的代码打包进最终的可执行文件，彻底摆脱对外部模块文件的依赖：

1. 编译自定义模块为静态库
   对每个自定义模块（如common.py）执行以下命令：

   # 将Python文件转为C文件
   python3 -m cython -3 common.py
   # 编译C文件为目标文件（-fPIC确保位置无关，用于静态库）
   gcc -c -fPIC -I/usr/include/python3.10 common.c -o common.o
   # 打包为静态库
   ar rcs libcommon.a common.o
   

2. 编译主模块并链接静态库
   处理入口文件main.py，并将静态库链接到最终可执行文件：

   # 生成带入口函数的主C文件
   python3 -m cython --embed -3 -o main.c main.py
   # 编译链接所有静态库和主C文件，生成独立可执行文件
   gcc -Os -I/usr/include/python3.10 main.c libcommon.a -lpython3.10 -o myapp
   

   若有多个自定义模块，只需重复步骤1生成对应静态库，然后在gcc命令中添加所有静态库（如libcommon.a libutils.a）。

方法2：修改模块搜索路径（临时 workaround） #

如果不想使用静态库，可在main.py开头添加代码，让Python解释器能找到模块所在路径：

import sys
import os

# 获取当前可执行文件的目录
exe_path = os.path.abspath(sys.argv[0])
exe_dir = os.path.dirname(exe_path)
# 将目录加入模块搜索路径的最前面
sys.path.insert(0, exe_dir)

但这种方法需要将编译后的模块文件（如common.so）和可执行文件放在同一目录，并非完全独立，仅适合临时场景。

关键注意事项 #

• 编译静态库时必须添加-fPIC参数，否则链接阶段会出现位置无关代码相关错误。
• 确保所有自定义模块都被编译为静态库并参与链接，避免Python解释器在运行时尝试从文件系统加载模块。

内容的提问来源于stack exchange，提问作者Simon T.