如何将 YOLOv5 的 detect.py 打包为独立可执行文件（.exe）-Python教程

本文详解使用 pyinstaller 将 yolov5 的 detect.py 成功打包为 windows 可执行文件的关键步骤，重点解决因模块路径、字节码缺失及资源引用异常导致的运行时错误（如 `general.pyc not found` 或 `unicodedecodeerror`）。

将 YOLOv5 项目（尤其是 detect.py）打包为单文件 .exe 是部署推理服务或交付给无 Python 环境用户的常见需求。但直接运行 pyinstaller detect.py 往往失败——并非缺少第三方库，而是 YOLOv5 的模块组织方式（如 utils/、models/ 下的子模块）未被 PyInstaller 自动识别和收集，导致运行时找不到 utils.general 等关键模块，甚至误加载残缺 .pyc 文件引发 UnicodeDecodeError。

✅ 正确打包方案（推荐命令）

使用以下 PyInstaller 命令，兼顾模块发现、数据资源嵌入与兼容性：

pyinstaller -F --noconsole --onedir \
    --add-data "weights;weights" \
    --add-data "data;data" \
    --hiddenimport=utils.general \
    --hiddenimport=utils.torch_utils \
    --hiddenimport=utils.datasets \
    --hiddenimport=models.common \
    --hiddenimport=models.yolo \
    --collect-all torch \
    detect.py

? 参数说明： -F：生成单个 .exe 文件（若需调试建议先用 –onedir）； –noconsole：隐藏控制台窗口（如需日志输出可改为 –console）； –add-data：显式包含模型权重（weights/）、配置文件（data/）等运行时必需目录（格式：源路径;目标路径，Windows 用分号）； –hiddenimport：强制告知 PyInstaller 加载指定模块（避免动态导入被忽略）； –collect-all torch：确保 PyTorch 相关二进制依赖完整（尤其对 torchvision ops 至关重要）。

⚠️ 关键注意事项

• 切勿手动复制 .pyc 文件：如问题中尝试将 __pycache__/general.cpython-3x.pyc 改名放入 utils/，会导致字节码版本不匹配或编码损坏，触发 UnicodeDecodeError。PyInstaller 应自动编译并嵌入源码，无需干预字节码。