auto-py-to-exe 实战指南：用图形界面把 Python 脚本一键打包成 .exe

• 开发工具
• 桌面应用

auto-py-to-exe 是一个基于 PyInstaller 的 .py 转 .exe 图形化打包工具，它把 PyInstaller 纷繁复杂的命令行参数封装成可视化的 Web 界面，让开发者无需记忆参数即可完成单文件（Onefile）、窗口程序（Window Based）、资源附带等常见打包场景。本文以仓库内的官方文档（README-Bulgarian.md，即英文 README 的保加利亚语译本）为核心骨架，结合 auto_py_to_exe 包的源码实现，系统讲解它的环境要求、安装方式、界面操作流程、全部命令行参数、JSON 配置文件的导入导出，以及从点击按钮到 PyInstaller 真正执行的底层调用链。读完本文，你将能够独立完成从pip install到产出可分发 .exe 的完整流程，并理解打包失败时的排查方向。

项目定位：用 GUI 封装 PyInstaller

auto-py-to-exe 的核心思路并不复杂：它本身不执行打包，而是调用 PyInstaller 中可以直接看到：打包入口package()接收的正是pyinstaller_command字符串，通过shlex.split解析后调用PyInstaller.__main__.run执行。

因此，本文后面讲到的所有界面选项、JSON 字段，本质上都是 PyInstaller 参数的图形化映射——理解了这一点，你就掌握了排查打包问题的钥匙。

环境要求

官方文档（README-Bulgarian.md）列出的前提条件非常简单：

• Python 版本：3.6 ～ 3.12（注意，PyInstaller 与 Python 版本存在强绑定关系，超出该区间不保证可用）

关于浏览器，文档特别说明：要让界面呈现与官方截图一致的显示效果，需要安装 Chrome；如果未安装 Chrome，或启动时传入了--default-browser参数，则会使用系统默认浏览器打开界面。

从源码看，界面展示的完整逻辑在 ui.py 的start()函数中：程序启动时会依次检测 Chrome（chrome.find_path()）和 Edge（edge.find_path()），按「Chrome → Edge → 默认浏览器 → 无浏览器（仅打印地址）」的优先级降级。这也对应了 config.py 中定义的UIOpenMode三种模式：CHROME_OR_EDGE、DEFAULT_BROWSER、NONE。

安装与启动的三种方式

方式一：通过 PyPI 安装（推荐）

$ pip install auto-py-to-exe

启动：

$ auto-py-to-exe

如果机器上安装了多个 Python 版本，auto-py-to-exe命令可能指向错误的环境，此时应改用python -m auto_py_to_exe。

方式二：从源码安装

$ git clone https://gitcode.com/gh_mirrors/au/auto-py-to-exe.git $ cd auto-py-to-exe $ python setup.py install

启动方式同上，执行auto-py-to-exe即可。

方式三：本地运行（不安装，适合开发调试）

1. 克隆或下载仓库代码；
2. 在终端中进入项目根目录；
3. 执行python -m pip install -r requirements.txt安装依赖；
4. 执行python -m auto_py_to_exe启动应用，此时会打开一个运行着该项目的 Chrome 应用窗口。

需要注意：执行第 4 步时，当前终端必须位于auto_py_to_exe包所在目录（即步骤 3 之后的项目根目录）；如果不在，则需要用绝对路径或相对于当前位置的相对路径指明auto_py_to_exe文件夹的位置。

仓库还保留了一个兼容性入口 run.py，它会把python run.py伪装成python -m auto_py_to_exe来执行，以确保官方演示视频中的旧指令仍然有效。

图形界面使用流程：四步完成打包

启动 auto-py-to-exe 后，官方文档给出了极为简明的四步操作法：

1. 选择脚本位置：在 "Script Location" 输入框粘贴脚本路径，或通过文件管理器选择。输入后，若文件真实存在，输入框的轮廓会变为蓝色（这是前端通过后端暴露的does_file_exist接口实时校验的结果，见 ui.py）；
2. 配置其余选项：根据需求选择 Onefile / One Directory、Console / Window Based 等，并可通过对话框添加图标（icon）、附加数据文件（datas）等资源；
3. 点击底部的大蓝色按钮执行转换；
4. 打包完成后在/output目录中查找产物。

文档用「Easy.」一词收尾，强调其零学习成本——这正是图形界面的价值所在：PyInstaller 的参数被「翻译」成可勾选的选项、可拖入的文件路径和开关按钮。

文件选择、图标校验等交互细节均有源码支撑：文件选择对话框由 dialogs.py 基于 tkinter 实现，支持按类型过滤（*.py;*.pyw、*.ico、*.json）；图标校验逻辑is_file_an_ico会读取文件头 4 字节并比对\x00\x00\x01\x00是否为有效 ICO 魔数（见 ui.py）。

命令行参数详解

官方文档给出了完整的参数表。使用方式为：

auto-py-to-exe [-db] [-c [CONFIG]] [-o [PATH]] [filename]

如果以本地方式运行该包，需要用python -m auto_py_to_exe替代auto-py-to-exe命令。

从源码看参数的真实行为

以上参数在main.py 中通过argparse逐一定义，并映射到 config.py 的全局配置：

• filename经过validation.argparse_file_exists校验，文件不存在会直接报错File does not exist，最终以绝对路径写入config.package_filename；
• -c/--config经过validation.argparse_file_json校验，要求文件存在且可被json.load解析，解析结果写入config.supplied_ui_configuration，由界面初始化时读取并回填各字段（对应 ui.py 中initialise()暴露的suppliedUiConfiguration）；
• -o/--output-dir默认值为"output"，会被os.path.abspath转为绝对路径后写入config.default_output_directory，因此不指定时产物默认落在当前目录下的output/；
• -nu/--no-ui会把ui_open_mode置为NONE：此时 UI 不再被打开，程序只在终端打印类似Server starting at http://localhost:{port}/index.html的地址，且文档强调「使用该选项时必须手动用 Ctrl+C 停止应用」（对应 ui.py 中mode=None的服务模式）；
• -bdo/--build-directory-override要求传入一个已存在的目录（--build-directory-override must be a directory校验见main.py），其作用是替代默认的临时构建目录tempfile.mkdtemp()。

此外，源码还额外提供了两个文档表格未列出的参数，可视为进阶用法：

JSON 配置文件：让打包配置可复用、可分发

为什么需要 JSON 配置

如果每次打包都要在界面里重新填写脚本路径、勾选选项，既繁琐又容易出错。官方文档给出的解决方案是：进入设置（Settings）选项卡的Configuration（配置）区域，把界面当前状态导出为 JSON 文件；下次打开界面时再导入该文件，所有字段即可自动回填。

配置导入导出的实现细节

这一功能的前端逻辑位于 importExport.js：

• 导出时，前端调用eel.export_configuration(data)，由后端 ui.py 的export_configuration弹出保存对话框，并把 JSON 以缩进格式写入磁盘；
• 导入时，前端调用eel.import_configuration()，由后端读取用户选中的 JSON 文件后返回内容，前端再通过「配置清理器 + 配置设置器」机制把每个optionDest回填到对应控件（详见 importExport.js 与 configuration.js）；
• 导入会先清空当前界面所有配置，因此若当前存在未完成的打包命令，界面会弹出确认对话框提醒用户。

配置文件的结构

导出的 JSON 顶层包含两个键（仓库中的 examples/1-basic/auto-py-to-exe-config.json 即为真实样例）：

{ "version": "auto-py-to-exe-configuration_v1", "pyinstallerOptions": [ { "optionDest": "filenames", "value": "./main.py" }, { "optionDest": "onefile", "value": true }, { "optionDest": "console", "value": true } ] }

• version：配置格式版本标识，当前为auto-py-to-exe-configuration_v1；
• pyinstallerOptions：数组，每一项的optionDest对应 PyInstaller 参数的 dest 名（如filenames、onefile、console、datas等），value为对应值；
• nonPyinstallerOptions：auto-py-to-exe 自身的选项，包括increaseRecursionLimit（是否提升递归限制）、manualArguments（手动追加的原始命令行参数）、outputDirectory（输出目录）。

关于输出目录的重要提示

文档特别提醒：导出 JSON 配置时不会自动保存输出目录，因为迁移到另一台机器时目录结构可能完全不同。如果你确实希望把输出目录写进配置文件，需要在 JSON 的nonPyinstallerOptions下手动新建outputDirectory键。例如：

{ "version": "auto-py-to-exe-configuration_v1", "pyinstallerOptions": [], "nonPyinstallerOptions": { "outputDirectory": "D:\\dist\\my-app", "increaseRecursionLimit": false, "manualArguments": "" } }

前端在导入时读到该键后，会直接写入界面中的输出目录输入框（见 importExport.js）；而导出时则会被刻意剔除（delete nonPyinstallerConfiguration.outputDirectory），印证了「默认不保存」的设计。

更丰富的真实示例

仓库的 examples/ 目录提供了 4 个可直接套用的配置文件，覆盖常见打包场景：

• 1-basic：基础控制台程序，console为true；
• 2-no-console：无控制台（GUI 程序典型配置），console为false；
• 3-images-and-other-non-py-files：附带静态资源，使用datas字段把./assets目录打包进assets/；
• 4-persistent-data：持久化数据（如数据库文件）的打包方式。

以附加资源为例，对应的配置片段（见 examples/3-images-and-other-non-py-files/auto-py-to-exe-config.json）：

{ "optionDest": "datas", "value": "./assets;assets/" }

datas的值遵循 PyInstaller 的源路径;目标路径约定，分号前为本地资源路径，分号后为打包后 exe 内的目标目录。

配合命令行使用示例（来自 examples/1-basic/readme.md）：

# 在 examples/1-basic 目录下打开终端 $ auto-py-to-exe --config auto-py-to-exe-config.json # 点击底部蓝色 Convert 按钮完成打包 # 完成后点击 "OPEN OUTPUT FOLDER" 查看产物

打包原理：从点击按钮到生成 .exe 的完整链路

理解内部实现有助于在界面「转圈卡住」或产物异常时快速定位问题。整个链路分为四层：

1. 前端组装命令：前端 configuration.js 的getCurrentCommand()会把当前界面状态拼装成一条形如pyinstaller --noconfirm --onedir --console ... "main.py"的命令字符串，并实时显示在界面的 "Current Command" 文本框中——这也是一个值得利用的特性：你可以随时查看界面将执行的原始命令，并用它复现问题；
2. 后端透传：点击打包按钮后，前端调用eel.package(command, non_pyinstaller_options)（ui.py），把命令和increaseRecursionLimit、outputDirectory两个非 PyInstaller 选项交给 Python 侧；
3. 执行与重定向：packaging.py 的package()会追加--distpath、--workpath、--specpath三个参数，把 PyInstaller 的中间产物全部导向应用启动时创建的临时构建目录，然后执行run_pyinstaller。这里有个关键点：PyInstaller 的日志被重定向回界面输出区——ui.py 为PyInstaller和auto_py_to_exe两个 logger 各挂了一个自定义 StreamHandler，把日志实时转发到前端输出框；
4. 产物搬运：打包成功后，__move_package()会把临时dist目录中的所有文件移动到用户指定的输出目录（默认output/），并在目标已存在同名文件时先删除再覆盖（packaging.py）；若打包失败则不会移动产物。

打包前，前端还会调用will_packaging_overwrite_existing检测输出目录中是否已存在将被覆盖的 exe，并弹窗提醒用户（逻辑见 packaging.py）。

递归限制（Recursion Limit）与常见报错

界面的 Settings 区域有一个 "Increase Recursion Limit"（提升递归限制）开关，对应nonPyinstallerOptions.increaseRecursionLimit。它的作用在源码中一目了然：开启时sys.setrecursionlimit(5000)，关闭时恢复 Python 默认值（见 packaging.py）。当你的项目依赖深度递归（例如某些大型库），PyInstaller 可能报RecursionError: maximum recursion depth exceeded，此时勾选该开关往往就能解决。

版本兼容性 shim

在 Python 3.12 下，shims.py 会在启动时自动为较旧版本的 bottle 库（≤0.12.25）安装一个find_spec补丁，修复ModuleNotFoundError导入问题，保证界面服务正常启动。这说明项目对较新 Python 版本做了主动适配。

多语言支持与 -lang 语言参数

auto-py-to-exe 的界面和 README 支持数十种语言，保加利亚语（Български）正是其中之一。界面的语言映射表定义在前端 i18n.js 的translationMap中，共 62 处界面文本支持bg（保加利亚语）翻译；可用语言的代码列表见supportedLanguages（i18n.js）。

常用语言代码包括：

使用-lang参数即可指定界面默认语言，例如：

$ auto-py-to-exe -lang bg

语言检测的优先级为：-lang命令行参数（config.language_hint）→ 浏览器语言 → 默认语言en；若指定代码不在支持列表中，会回退到en（见 i18n.js）。中文用户使用-lang zh即可让界面以简体中文呈现。

仓库还提供了多个语言的 README 译本，中文版见 README-Chinese.md，保加利亚语版即本主题文档 README-Bulgarian.md，其余可参考 README-Finnish.md、README-Turkish.md、README-Persian.md、README-Korean.md、README-Hebrew.md、README-Hindi.md、README-Belarusian.md。

版本约束与 Python 2.7 兼容说明

官方文档明确指出：自 2020 年 8 月 9 日发布的PyInstaller v4.0起，Python 2.7 不再被支持。如果必须用 Python 2.7 使用本工具，需要降级安装 PyInstaller——PyInstaller v3.6 是最后一个支持 Python 2.7 的版本。操作步骤为：先卸载环境中现有的所有 PyInstaller，再执行：

$ python -m pip install pyinstaller==3.6

需要注意，此方案属于历史兼容路径，仅适用于旧项目；对新建项目应使用文档推荐的 Python 3.6～3.12 组合。

此外，utils.py 的get_warnings()会在启动时进行多项环境体检并给出提示，包括：PyInstaller 与 Python 3.7/3.8/3.9/3.10 的版本匹配要求（例如 Python 3.10 至少需要 PyInstaller 4.6）、Python 3.10.0 存在已知的 PyInstaller 崩溃 Bug、以及不推荐使用 Windows Store 安装的 Python（其发布包结构不被 PyInstaller 支持，可能报win32ctypes相关错误）。若界面顶部出现警告，请按提示升级对应组件。

运行测试

仓库的测试集中在 tests/ 目录，使用 pytest 运行：

$ pip install pytest $ pip install -e . $ pytest

其中 tests/test_packaging.py 展示了最有价值的端到端验证：在 Windows 上执行一次完整的pyinstaller --noconfirm --onedir --nowindowed打包，断言输出目录中生成了预期的 exe，并通过subprocess运行该 exe 校验其标准输出为Test\r\n。这份测试代码可以作为理解「最小可复现打包流程」的范本。另有 tests/test_imports.py 验证包入口可正常导入、tests/test_library_dependencies.py 校验 Eel 与 PyInstaller 关键函数的存在性。

常见问题排查建议

官方文档就使用问题给出了两条明确指引：

1. 产物或工具本身行为异常：文档推荐参考作者撰写的《Issues When Using auto-py-to-exe》博客文章（详见仓库 README-Bulgarian.md「Проблеми при Използването на Инструмента」一节），其中覆盖了打包 Python 脚本时应当了解的核心知识，以及常见困惑点的解决方案；
2. 确认是工具自身的缺陷：按 Bug 报告模板提交 issue，并在描述中清楚说明发生了什么、给出可复现步骤与最小可复现示例（Minimal Reproducible Example），以及你期望的行为——缺少这些信息会显著拖慢问题定位速度。若问题仅与你的具体应用有关，则不应在项目仓库中提交，而应到社区讨论区求助。

结合前文的源码分析，这里再补充几条实践建议：

• 打包前先看界面顶部的 "Current Command" 文本框，确认生成的命令符合预期；
• 勾选 "Increase Recursion Limit" 可缓解深层递归依赖导致的RecursionError；
• 使用--logging-level DEBUG可让终端输出更详细的日志，便于定位启动阶段的异常；
• 若杀毒软件频繁误删构建产物，使用-bdo指定一个白名单目录作为构建目录；
• 多机复用配置时，使用--config导入 JSON 文件，并留意输出目录需按目标机器环境单独设置。

• 开发工具
• 桌面应用