[开源][2.7.12 ]Python代码一键打包工具QPyPack！

QweJay

一款基于 PyInstaller 与 Nuitka 的跨平台 Python 应用可视化打包构建工具

QPyPack 是一款致力于简化 Python 应用打包流程的可视化工具。它深度整合了 PyInstaller 与 Nuitka 两大主流编译引擎，将繁琐的终端命令行参数转化为直观、便捷的图形界面交互，帮助开发者更高效、高成功率地生成跨平台原生可执行程序。

---

🚀 核心特性 (Key Features)

为了降低传统命令行构建的配置成本，解决多平台下环境与依赖冲突问题，QPyPack 深度整合了以下工程化辅助功能：

1. 直观的可视化交互体验

• 📥 拖放式载入 (Drag & Drop)：无需手动拷贝路径，直接将 .py 或 .pyw 源代码文件拖放至软件窗口，系统将全自动解析并载入工作区。
• 🎨 图标智能检索与自适应：源程序导入后，系统会自动检索同级目录下的常用图像资产（如 icon.ico / logo.ico / icon.svg / logo.svg）进行自适应格式转换、自动绑定与高清预览。
• 🌐 多语言支持 (i18n)：原生支持简体中文、英文等多语言界面自由切换，为全球开发者提供零门槛、无障碍的使用体验。

2. 依赖解析与虚拟环境沙盒

• 🛡️ 虚拟环境隔离 (Virtualenv Sandbox)：支持一键在系统临时目录下创建隔离的虚拟沙盒，仅安装应用运行所需的最小依赖项，从而有效精简最终可执行产物的体积。
• 🔍 多维度依赖解析：
  • 配置同步：自动检索并优先读取项目目录下的 requirements.txt 依赖声明。
  • AST 静态扫描：提供辅助的 AST（静态语法树）深度分析，自动提取代码中导入的非标准库模块，精准补齐隐式导入依赖（Hidden Imports）。
• ⚡ 内置 PyPI 加速源：预设主流镜像加速通道，大幅提升沙盒中拉取构建引擎与依赖库的速度。

3. 高级编译参数精准控制

• ⚙️ 双引擎自适应切换：在图形界面上实现 PyInstaller 与 Nuitka 的无缝切换，参数面板与优化选项将根据所选引擎的特性进行自适应调整。
• 📝 应用元数据注入 (Metadata)：无需编写繁琐的规格文件，直接在界面输入版本号、公司名和产品描述，工具会自动将元数据注入二进制程序属性中（支持 Windows PE 结构和 macOS Info.plist 写入）。
• 📂 附加资源可视化管理 (Data Files)：支持通过列表交互分别导入文件或文件夹，并支持双击列表条目直接修改打包后的相对释放路径（自适应释放路径映射）。---

⚡ 快速上手 (Quick Start)

您可以通过以下两种方式之使用 QPyPack：

方法一：通过 pip 安装并运行

在 Python >= 3.8 的环境中，执行以下命令进行安装与启动：

# 安装 QPyPack
pip install qpypack

# 启动程序
qpypack

方法二：下载二进制文件

如果您不想配置本地 Python 环境，可直接在 Release 页面下载对应系统的预编译打包版本：
👉 下载页面

---

📅 更新日志 (Changelog)

[2.7.12] - 2026-08-24

新增

• 增强常用包与生态映射：扩充 DEFAULT_MAPPINGS ，防止依赖误识别；新增对夸克网盘目录锁定的安全预警。
• 扩展 UI 框架智能识别：GUI 探测库新增 qtpy、pyglet、toga、pyqtgraph，自动适配“隐藏控制台”属性。
• 升级 Python 在线安装适配链：重构内置解释器安装矩阵与支持等级，适配 Python 3.14+ 现代化运行时生命周期，优化高低版本兼容推荐策略。

更改

• 默认启用 Nuitka 防膨胀机制：Nuitka 引擎默认启用 anti-bloat 插件与基础测试模块拦截规则，解决默认兼容模式下打包体积异常暴增的问题。
• 优化自动化资源全量收集：为 PyInstaller 与 Nuitka 引擎的自动收集规则追加 pyecharts 和 pyppeteer 支持，避免图表发白与浏览器驱动丢失。
• 强化 UPX 动态库安全白名单：UPX 排除规则进一步扩充至 Qt5 系列、sqlite3.dll 及 libcrypto/libssl，防止加壳损坏数据库与 HTTPS 网络组件。

修复

• 修复云盘与杀软文件死锁导致的构建中断：移除 Nuitka 的 --remove-output 参数，改由 QPyPack 接管清理，解决 OneDrive 同步锁或杀毒软件占用引发的 FATAL 致命报错。
• 修复内置标准库误报与冗余安装：补齐内置标准库清单中遗漏的 traceback 与 warnings，修复 Python 3.9 等低版本环境下将其误判为第三方依赖并尝试 pip 下载报错的问题。

  [2.7.3] - 2026-08-04

新增

• Python 环境管理器：新增环境管理弹窗，支持本地已安装 Python 的智能识别切换，以及官方/国内镜像源的一键下载安装。
• 文件夹打包模式：运行模式新增文件夹模式，并支持自定义内部资源目录名。
• 原生 AST 依赖分析：全面重构依赖扫描机制，使用原生 AST 解析替代 pipreqs，大幅提升隐式依赖分析速度与准确度。
• Playwright 镜像加速：新增 Playwright 浏览器驱动的镜像源下载及官方 CDN 自动回退机制。

改进

• UPX 动态避让：升级 UPX 压缩策略，自动识别并排除当前 Python 版本的核心 DLL 及 vcruntime140_1.dll，防止报错。
• 线程与中断控制：强化构建取消与清理逻辑，避免线程残留与临时文件锁死。
• 平台兼容与超时保护：优化 macOS Bundle Identifier 生成逻辑，增加命令执行超时保护机制。
• 界面细节调整：重构打包模式单选区域，精简关于页面布局与间距，更新版权标识。
• 国际化翻译：更新部分文字表述及翻译。

---

[2.7.0] - 2026-08-01

新增

• Nuitka 自动编译器嗅探与探测：新增对 Clang (LLVM) 与 Zig（专为 Python 3.13+ C 后端优化）编译器的自动探测与调用支持，优先与系统 MSVC (--msvc=latest) 或 Clang 自动匹配。
• 免配置第三方库打包预设：内置对 ttkbootstrap、customtkinter、playwright、moviepy 等高频报错/丢失资源库的自动化 --collect-all 与 --collect-data 处理，实现零配置打包。
• 双模式实时日志查看器：引入“精简模式 (Concise)”与“详细模式 (Detailed)”双视图日志查看器，支持在面板上方一键无缝实时切换、清空与导出日志。
• 智能 Python 平台兼容性提示：设置页面的 Python 解释器选择器新增动态指示卡片，实时展示对 Windows 7/8/10/11、macOS 及 Linux 的支持状态与官方下载引导。
• 构建容错与降级保护机制：新增编译前物理内存与磁盘空间评估；遭遇 ZstdError (OOM 内存溢出) 时自动触发单线程 (--jobs=1) 降级重试；遭遇杀毒软件或系统锁定图标时自动触发剥离图标降级构建。

修复

• 源码 BOM 与编码解析兼容：修复处理包含特殊 BOM (utf-8-sig) 或非标准系统回退编码的源码时，AST 模块可能抛出解码异常导致扫描中断的问题。
• 云盘锁定感知与预警：修复工作所在目录受 OneDrive / Dropbox 等云盘锁定同步时，缺乏明确预警导致打包中断的问题。
• 控制台程序运行时崩溃：修复因控制台“按回车退出逻辑与源码语法块作用域/闭合冲突引发的崩溃问题。

改进

• AST 解析引擎原生化重构：将源码隐式依赖扫描由子进程调用彻底重构为同进程原生 AST 模块解析，大幅降低系统资源开销并成倍提升扫描速度。
• 环境检索异步并发加速：引入多线程异步并发检测机制，对系统内所有候选 Python 环境进行并行嗅探与版本校验，彻底消除软件启动时的 I/O 卡顿。
• 纯矢量 UI 规范与 Emoji 清理：全面清理侧边栏、Tab 标签及语言列表中的 Emoji 表情，全量升级为 Google Material SVG 矢量图标栈，解决 Linux 及老旧 Windows 系统下的字体回退乱码与排版跳动问题。
• 卡片式动态构建状态反馈：主面板拖拽区与状态栏支持实时捕获并渲染编译引擎（Nuitka / Scons / PyInstaller）极细粒度的编译进度文本，大幅缓解打包等待焦虑。
• 重构“关于”页面与赞助交互：全新设计“关于”选项卡，引入可视化 GitHub、PyPI、Issues 动作行按钮及自愿赞助模块。
• 依赖安装弹性降级策略：重构 pip 依赖构建逻辑，采用统一原子依赖清单；当指定严格版本号（==）安装失败时，自动剥离版本约束并拉取最新兼容版本。
• 跨平台原生字节流图标生成：剥离对 macOS sips 命令行工具的强依赖，重构纯 Python 原生字节流拼装机制处理跨平台 .ico 与 .icns 生成。
• 扩展第三方包名映射库：扩展内置包名映射字典，补充 pyside6_addons、pyside6_essentials、attrs、psycopg2-binary 等常见第三方包映射。

---

🤝 参与贡献 (Contributing)

我们非常欢迎您的参与！如果您在测试或使用过程中发现任何异常，或者有更好的优化建议，可以通过以下方式参与贡献：

1. 提交反馈：在项目主页提交 GitHub Issues，并附带异常日志。
2. 提交代码：欢迎提交 Pull Requests，请在提交前确保您的代码符合标准规范并完成了多平台本地测试。

---

📄 开源协议 (License)

本项目基于 GNU General Public License v3.0 开源，允许在遵循协议条款的前提下自由分发、修改和二次开发。

[!NOTE]
关于打包产物的版权：
使用 QPyPack 构建生成的二进制文件/应用程序，其版权和开源许可完全由使用者自行决定，QPyPack 的 GPL-3.0 协议不会影响用户打包后的程序。

Copyright (C) 2026 QwejayHuang.

蓝奏云：
https://qwejay.lanzouu.com/b0fqgtnej
密码回复可见。密码:4i9u

🚀 QPyPack 快速入门教程

QPyPack 是一款跨平台 Python 程序打包工具，可将 Python 代码编译并封装为独立可执行文件（.exe 或 .app）。生成的程序脱离 Python 环境运行，支持在目标设备上双击直接打开。

---

零、 启动与部署

根据使用场景选择合适的启动方式：

方式一：独立免安装版（推荐：未配置 Python 环境的用户）

1. 前往 Release 发布页面下载对应系统的压缩包：👉 下载预编译版本 (GitHub Releases)
2. 解压后运行主程序即可启动，无需预先安装 Python 环境。

方式二：通过 pip 安装（推荐：Python 开发者）

若本地已安装 Python 3.8 及以上版本，可在终端或命令行中执行：

pip install qpypack    # 安装工具
qpypack                # 启动程序

---

一、 标准打包工作流

完成程序打包仅需以下三个步骤：

1. 拖入代码：将入口程序文件（如 main.py）拖拽至主区域虚线框内。
2. 开始打包：点击底部的 [开始构建] 按钮。等待界面显示绿色的 “Build Successful” 提示即完成打包。
3. 基础配置：点击右下角 [构建设置] 按钮进行基本配置：
   • 输出名称：设置生成软件的自定义名称。
   • 应用图标：选择软件图标（Windows 平台推荐使用 .ico 格式）。
   • 单文件模式 (--onefile)：勾选后将所有依赖打包为单一可执行文件，便于分发。
   • 隐藏控制台 (--noconsole)：
     • 带有图形界面的程序（如 PyQt、Tkinter）：建议勾选（隐藏命令行窗口）。
     • 命令行交互程序：无需勾选（保留控制台窗口）。

---

二、 进阶配置指南

项目包含静态资源或较多第三方依赖时，可通过配置面板进行优化：

1. 构建引擎选择

• PyInstaller（默认推荐）：构建速度快，兼容性优异，适用于绝大多数标准项目。
• Nuitka（深度编译与防护）：将 Python 代码翻译并编译为 C/C++ 机器码，具有极强的反编译防护能力，同时提升运行效率。
  注：首次使用 Nuitka 时，系统会自动下载后台编译工具，请保持网络通畅。

2. 依赖管理

• 使用虚拟环境：勾选后系统将创建独立的沙盒环境，仅打包项目实际用到的依赖库，有效控制体积。
• AST 扫描：点击 [AST 扫描] 按钮，系统将自动分析源码语法树并补全隐藏的第三方依赖。
• 镜像源加速：内置国内主流镜像源，支持主备源自动切换，提高依赖下载成功率。

3. 附加资源管理

若程序依赖图片、配置文件或音频等静态资源：

1. 切换至 [附加资源] 标签页，将所需资源文件或文件夹拖入列表中。
2. 路径处理注意：在单文件模式下，资源会在运行时解压至临时目录。代码中读取资源路径时，需结合 sys._MEIPASS 进行动态定位。

4. 性能与体积优化

• 精简模式：自动应用字节码优化，并剔除构建环境中不必要的开发与测试组件（如 pytest）。
• 内存保护机制：打包大型项目导致内存紧张时，系统会自动降级为单线程模式继续构建，提高稳定性。

---

三、 零 Python 环境装配系统

若目标打包设备未安装 Python 环境，QPyPack 提供全自动环境补全方案：

1. 自动拦截提示：使用免安装版 QPyPack 且系统缺失 Python 环境时，点击 [开始构建] 将自动弹出 [Python 环境管理] 窗口。
2. 一键安装环境：直接在弹窗中选择推荐版本（如 Python 3.11.9）并点击 [一键下载并安装]。系统将自动下载、安装并配置环境变量。
3. 版本兼容预检：若代码使用了高版本语法，而选择的打包环境版本较低，系统会自动拦截并精准定位不兼容的代码行，提示切换环境。

---

四、 自定义包名映射机制

部分 Python 库的代码导入名称（Import Name）与 PyPI 注册包名（Package Name）不一致（例如代码中为 import cv2，实际安装包名为 opencv-python）。

QPyPack 提供内置并可扩展的包名映射机制：

• 内置预设：默认预设数十种常用映射关系（如 fitz ➔ pymupdf、docx ➔ python-docx）。
• 自定义扩展：如需使用私有库或新开源库，可在 [构建设置] ➔ [包名映射] 中点击 [添加映射] 手动配置对应关系。

---

五、 元数据与图标管理

1. 版本与版权信息注入：在 [偏好设置] ➔ [元数据与预设] 中可配置版本号、作者信息与软件描述。打包后相关信息将注入 PE 头部（Windows 可在文件属性中查看）。
2. 图标自动转换：Windows 需要 .ico 格式，macOS 需要 .icns 格式。直接上传 .png 或 .jpg 图片，系统会自动完成无损缩放与格式转换。

---

六、 日志监控与诊断系统

1. 双视图日志模式：
   • 精简日志：默认开启，仅展示构建关键节点与错误提示，保持界面简洁。
   • 详细日志：可切换查看完整的输出日志与错误日志，便于排查底层异常。
2. 语法错误诊断：若源码存在语法错误（如缩进错误或缺失括号）导致构建中断，诊断引擎将精确定位出错的文件名、代码行号与异常细节。

---

七、 问题反馈与日志提交

若在构建过程中遇到异常，欢迎提交反馈。为快速定位问题，提交反馈时请附带完整的构建日志。

1. 打包日志提取方式

• 方式一：手动导出日志（推荐）
  在主界面日志区域点击右键，选择 [导出日志...] 保存为 .log 文件。
• 方式二：开启日志自动保存
  在 [偏好设置] 中勾选 [自动保存日志]，构建完成后输出目录会自动生成 qpypack_应用名.log 文件。
• 方式三：详细日志复制
  若遇到编译异常，可切换至 [详细日志] 模式，复制完整报错堆栈。

2. 反馈提交说明

• 提交渠道：👉 提交 Issues / 问题反馈 (GitHub)
• 建议提供信息：
  1. QPyPack 版本号（如 v2.7.3）
  2. 操作系统类型（如 Windows 11 x64 / macOS Sonoma）
  3. 构建引擎及 Python 版本（如 PyInstaller + Python 3.11）
  4. 异常现象简述及导出的 .log 日志文件

QweJay

开源无私贡献不容易，希望给个STAR，谢谢！下载地址：https://github.com/Qwejay/PyPack

QweJay

求知教育 发表于 2026-8-4 16:03
大佬，有使用教程吗？我用ai开发了个基于python的 微课学习系统（是一个文件夹），我想把他压缩成exe，让其 ...

🚀 QPyPack 快速入门教程

QPyPack 是一款跨平台 Python 程序打包工具，可将 Python 代码编译并封装为独立可执行文件（.exe 或 .app）。生成的程序脱离 Python 环境运行，支持在目标设备上双击直接打开。

---

零、 启动与部署

根据使用场景选择合适的启动方式：

方式一：独立免安装版（推荐：未配置 Python 环境的用户）

1. 前往 Release 发布页面下载对应系统的压缩包：👉 下载预编译版本 (GitHub Releases)
2. 解压后运行主程序即可启动，无需预先安装 Python 环境。

方式二：通过 pip 安装（推荐：Python 开发者）

若本地已安装 Python 3.8 及以上版本，可在终端或命令行中执行：

pip install qpypack    # 安装工具
qpypack                # 启动程序

---

一、 标准打包工作流

完成程序打包仅需以下三个步骤：

1. 拖入代码：将入口程序文件（如 main.py）拖拽至主区域虚线框内。
2. 开始打包：点击底部的 [开始构建] 按钮。等待界面显示绿色的 “Build Successful” 提示即完成打包。
3. 基础配置：点击右下角 [构建设置] 按钮进行基本配置：
   • 输出名称：设置生成软件的自定义名称。
   • 应用图标：选择软件图标（Windows 平台推荐使用 .ico 格式）。
   • 单文件模式 (--onefile)：勾选后将所有依赖打包为单一可执行文件，便于分发。
   • 隐藏控制台 (--noconsole)：
     • 带有图形界面的程序（如 PyQt、Tkinter）：建议勾选（隐藏命令行窗口）。
     • 命令行交互程序：无需勾选（保留控制台窗口）。

---

二、 进阶配置指南

项目包含静态资源或较多第三方依赖时，可通过配置面板进行优化：

1. 构建引擎选择

• PyInstaller（默认推荐）：构建速度快，兼容性优异，适用于绝大多数标准项目。
• Nuitka（深度编译与防护）：将 Python 代码翻译并编译为 C/C++ 机器码，具有极强的反编译防护能力，同时提升运行效率。
  注：首次使用 Nuitka 时，系统会自动下载后台编译工具，请保持网络通畅。

2. 依赖管理

• 使用虚拟环境：勾选后系统将创建独立的沙盒环境，仅打包项目实际用到的依赖库，有效控制体积。
• AST 扫描：点击 [AST 扫描] 按钮，系统将自动分析源码语法树并补全隐藏的第三方依赖。
• 镜像源加速：内置国内主流镜像源，支持主备源自动切换，提高依赖下载成功率。

3. 附加资源管理

若程序依赖图片、配置文件或音频等静态资源：

1. 切换至 [附加资源] 标签页，将所需资源文件或文件夹拖入列表中。
2. 路径处理注意：在单文件模式下，资源会在运行时解压至临时目录。代码中读取资源路径时，需结合 sys._MEIPASS 进行动态定位。

4. 性能与体积优化

• 精简模式：自动应用字节码优化，并剔除构建环境中不必要的开发与测试组件（如 pytest）。
• 内存保护机制：打包大型项目导致内存紧张时，系统会自动降级为单线程模式继续构建，提高稳定性。

---

三、 零 Python 环境装配系统

若目标打包设备未安装 Python 环境，QPyPack 提供全自动环境补全方案：

1. 自动拦截提示：使用免安装版 QPyPack 且系统缺失 Python 环境时，点击 [开始构建] 将自动弹出 [Python 环境管理] 窗口。
2. 一键安装环境：直接在弹窗中选择推荐版本（如 Python 3.11.9）并点击 [一键下载并安装]。系统将自动下载、安装并配置环境变量。
3. 版本兼容预检：若代码使用了高版本语法，而选择的打包环境版本较低，系统会自动拦截并精准定位不兼容的代码行，提示切换环境。

---

四、 自定义包名映射机制

部分 Python 库的代码导入名称（Import Name）与 PyPI 注册包名（Package Name）不一致（例如代码中为 import cv2，实际安装包名为 opencv-python）。

QPyPack 提供内置并可扩展的包名映射机制：

• 内置预设：默认预设数十种常用映射关系（如 fitz ➔ pymupdf、docx ➔ python-docx）。
• 自定义扩展：如需使用私有库或新开源库，可在 [构建设置] ➔ [包名映射] 中点击 [添加映射] 手动配置对应关系。

---

五、 元数据与图标管理

1. 版本与版权信息注入：在 [偏好设置] ➔ [元数据与预设] 中可配置版本号、作者信息与软件描述。打包后相关信息将注入 PE 头部（Windows 可在文件属性中查看）。
2. 图标自动转换：Windows 需要 .ico 格式，macOS 需要 .icns 格式。直接上传 .png 或 .jpg 图片，系统会自动完成无损缩放与格式转换。

---

六、 日志监控与诊断系统

1. 双视图日志模式：
   • 精简日志：默认开启，仅展示构建关键节点与错误提示，保持界面简洁。
   • 详细日志：可切换查看完整的输出日志与错误日志，便于排查底层异常。
2. 语法错误诊断：若源码存在语法错误（如缩进错误或缺失括号）导致构建中断，诊断引擎将精确定位出错的文件名、代码行号与异常细节。

---

七、 问题反馈与日志提交

若在构建过程中遇到异常，欢迎提交反馈。为快速定位问题，提交反馈时请附带完整的构建日志。

1. 打包日志提取方式

• 方式一：手动导出日志（推荐）
  在主界面日志区域点击右键，选择 [导出日志...] 保存为 .log 文件。
• 方式二：开启日志自动保存
  在 [偏好设置] 中勾选 [自动保存日志]，构建完成后输出目录会自动生成 qpypack_应用名.log 文件。
• 方式三：详细日志复制
  若遇到编译异常，可切换至 [详细日志] 模式，复制完整报错堆栈。

2. 反馈提交说明

• 提交渠道：👉 提交 Issues / 问题反馈 (GitHub)
• 建议提供信息：
  1. QPyPack 版本号（如 v2.7.3）
  2. 操作系统类型（如 Windows 11 x64 / macOS Sonoma）
  3. 构建引擎及 Python 版本（如 PyInstaller + Python 3.11）
  4. 异常现象简述及导出的 .log 日志文件

kai2025

支持下。打包PY成EXE的文件有没有办法压到10M内的。现在的源码才几十K.压成几十M的。。

QweJay

zhu791023529 发表于 2026-8-2 23:25
Error: : Executable doesn't exist at C:%users\ADMINI~1\AppData\Local\Temp\_MEI25882\playwright\drive ...

这个好像是Playwright的坑，chrome-headless-shell.exe被下载到了缓存目录，然后找不到。新版本我尝试修复。

jun269

看上去挺不错的，，但这个网站太难打开了，能给转个其它网盘了不？

etkane

帮你星标了，我是第三个星，祝你软件万星

aqtd2

能否给个其他链接

wyf0728

不能下载啊

redapple2015

[预处理] 清理遗留缓存...
[环境预配置] 正在初始化 Python 虚拟环境...
[环境配置] 正在通过镜像源 https://pypi.tuna.tsinghua.edu.cn/simple 部署依赖包...
[依赖解析] 未找到 requirements.txt，执行 AST 静态扫描...
发现外部依赖模块: PyQt5
[自动同步] 正在安装 PyQt5...
[编译阶段] 启动 Nuitka 构建...
[自动检测] 已启用 PyQt5 插件
Usage: python.exe -m nuitka [--mode=compilation_mode] [--run] [options] main_module.py

Note: For general plugin help (they often have their own
command line options too), consider the output of
'--help-plugins'.

__main__.py: error: The '--include-data-files' option requires an argument with '--include-data-files='.
[阶段收尾] 归档产物...
[错误] 未找到产物: C:\Users\XX\AppData\Local\Temp\nuitka_out_yfs10qn0\main.exe
[清理] 删除临时文件...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[构建失败] 请检查日志排查错误。

redapple2015

py打包让人头疼。我搞的虚拟环境换电也不能用。

kudoless

感谢楼主

rockiness

测试了一下  挺好用的