如何解决cx_Freeze打包含pdf2docx脚本时的mupdf导入错误？

方案1：手动指定pymupdf依赖文件 #

cx_Freeze经常没法自动识别pymupdf的核心动态库，得在打包配置里手动加进去：

• 修改setup.py，在build_exe_options里补充依赖包和必要文件：

from cx_Freeze import setup, Executable
import pymupdf
import os

# 获取pymupdf核心库路径，Windows用.pyd，Linux/macOS用.so
mupdf_lib_path = os.path.join(os.path.dirname(pymupdf.__file__), "mupdf.pyd")

build_exe_options = {
    "packages": ["pymupdf", "pdf2docx"],
    "include_files": [mupdf_lib_path]
}

executables = [Executable("你的脚本文件名.py")]

setup(
    name="PDF转DOCX工具",
    version="1.0",
    options={"build_exe": build_exe_options},
    executables=executables
)

• 运行打包命令时用这个修改后的setup.py，确保核心库被打包进去。

方案2：强制调整导入顺序 #

如果是导入顺序乱了导致循环依赖，直接在脚本最顶部先加载pymupdf：

import pymupdf
from pdf2docx import Converter

# 后面写你的批量转换代码

先把pymupdf加载完成，再导入pdf2docx，避免打包后加载顺序混乱触发循环导入错误。

方案3：换用PyInstaller打包 #

PyInstaller对第三方库的兼容性比cx_Freeze好很多，试试这个：

• 先装PyInstaller：pip install pyinstaller
• 执行打包命令：

pyinstaller --onefile --hidden-import=pymupdf --hidden-import=pymupdf.mupdf 你的脚本文件名.py

--hidden-import是强制让PyInstaller识别pymupdf的内部子模块，防止打包后找不到。

方案4：优化Nuitka打包参数 #

如果非要用Nuitka，调整打包命令参数，让它主动追踪pymupdf的所有依赖：

python -m nuitka --standalone --follow-imports --include-package=pymupdf --include-package=pdf2docx 你的脚本文件名.py

--follow-imports会强制Nuitka遍历所有导入的模块，--include-package明确指定要打包的库，避免卡在pymupdf.mupdf模块。

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