MacOS下cx_freeze编译Python程序出现Python路径错误求助

我经常碰到Mac上cx_freeze打包后跨环境运行失败的情况，大概率是依赖没被完整打包或者路径配置出了问题。结合你的情况，给你几个针对性的排查和解决步骤：

1. 先检查setup.py的依赖配置是否完整 #

很多时候是你没在setup.py里明确指定要包含的第三方模块或自定义包，cx_freeze的自动检测偶尔会漏掉一些隐式导入的依赖。

• 用packages参数指定你的自定义包路径，比如你的程序用到了my_utils包，就加上"packages": ["my_utils"]
• 用includes参数列出所有直接或间接用到的第三方模块，比如"includes": ["numpy", "requests", "pandas"]
• 打包时加上--verbose参数查看日志：python setup.py build --verbose，日志里会显示哪些模块被跳过或者没找到，针对性添加到includes里

2. 处理Mac系统框架和动态库依赖 #

Mac上的Python程序依赖很多系统框架（比如.framework）和动态库（.dylib），cx_freeze有时候不会自动把这些文件打包进去，导致卸载本地Python或在其他电脑上运行时找不到。

• 在build_exe_options里添加include_files参数，手动指定需要包含的系统文件：
  比如要包含当前Python的框架，可以用sys.executable动态获取路径：

  import sys
  build_exe_options = {
      # ...其他配置
      "include_files": [
          (sys.executable, "Python"),
          # 如果有特定的.dylib依赖，比如某个第三方库的动态库
          "/usr/local/lib/libssl.dylib",
      ]
  }
  

• 如果生成的是.app bundle，要确保所有依赖路径都用相对路径，避免绝对路径导致找不到文件。可以用install_name_tool工具修改依赖路径，比如把绝对路径改成@executable_path/../Frameworks/xxx.dylib

3. 用正确的打包命令并测试 #

你之前执行的python setup.py install是把程序安装到本地Python环境，并不是生成独立可执行文件，正确的打包命令是：

python setup.py build

生成的build目录里的文件就是独立的打包产物，把整个build文件夹拷贝到其他电脑或者卸载本地Python后测试。

4. 排查具体报错信息 #

虽然你没给出具体错误，但这类问题常见的是两种：

• ModuleNotFoundError：根据提示的缺失模块，把它添加到setup.py的includes或packages里
• dyld: Library not loaded：提示找不到某个动态库，把这个库的路径添加到include_files里，或者用otool -L your_executable查看可执行文件依赖的所有动态库，检查哪些是绝对路径，然后修改成相对路径

给你一个完整的setup.py示例参考：

import sys
from cx_Freeze import setup, Executable

# 你的主程序脚本
main_script = "test.py"

base = "Console"  # 如果是GUI程序改成"GUI"
if sys.platform != "darwin":
    base = None

build_exe_options = {
    "packages": [],  # 替换成你的自定义包
    "includes": [],  # 替换成你用到的第三方模块
    "include_files": [
        (sys.executable, "Python"),
        # 添加你需要的其他依赖文件
    ],
    "excludes": ["tkinter", "unittest"],  # 排除不需要的模块
    "optimize": 2,
}

executables = [Executable(main_script, base=base)]

setup(
    name="TestApp",
    version="1.0",
    description="My test application",
    options={"build_exe": build_exe_options},
    executables=executables
)

5. 环境一致性测试 #

最好用和目标系统版本一致的Mac环境打包（比如你要在Monterey上运行，就用Monterey系统打包），避免系统框架版本不兼容。也可以用虚拟机创建一个干净的Mac环境，测试打包后的程序是否能正常运行。

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