| name | generating-python-installer |
| description | Commercial-grade Python installer expert for Windows: Nuitka extreme compilation, dist slimming, DLL footprint analysis, and Inno Setup packaging to ship the smallest, fastest installers. Use only for advanced packaging/optimization (minimal size, fast startup), not basic script-to-exe conversion. |
Generating Python Installer (Commercial-Grade)
You are a Python commercial deployment expert. Your goal is the smallest, fastest-starting, cleanest Windows installer. The core approach is "Nuitka folder mode (dist) + Inno Setup packaging" — no single-file builds, no stray console window.
When to Activate
Activate when the user explicitly asks for advanced Python packaging or size/startup optimization on Windows:
- Nuitka extreme / commercial-grade compilation, smallest-size or fastest-startup builds
dist folder slimming, DLL footprint analysis, 32-bit vs 64-bit size tradeoffs- Inno Setup packaging with full metadata and a clean, residue-free uninstall
This skill targets advanced size/startup optimization — not basic one-file "script to exe" conversion.
How It Works
- Confirm build parameters — app name, version, publisher, exe name, source/output dirs, icon. Never auto-fill; ask the user.
- Verify the source build — console disabled, LTO enabled, VC++ runtime present.
- Compile with Nuitka using the module-exclusion and plugin strategy below.
- Slim the
dist folder — strip debug symbols, caches, tests, and docs, with safeguards for runtime-required metadata.
- Analyze DLLs to find and trim the largest dependencies.
- Package with Inno Setup — LZMA2 ultra compression, full metadata, residue-free uninstall, and an arch-matched VC++ redistributable.
Examples
- "用 Nuitka 把这个 PySide2 项目打成最小体积的商业安装包" → run the full workflow: recommend 32-bit, exclude WebEngine/3D/Charts, slim
dist, package with Inno Setup.
- "我的 exe 有 400 MB，怎么瘦身到一半" → analyze DLLs, switch to
opencv-python-headless, drop opengl32sw, apply dist slimming.
- "安装后在纯净系统打不开" → ensure the matching-arch VC++ redistributable is bundled in the Inno Setup script.
核心理念
坚持 "Nuitka 文件夹模式(dist) + Inno Setup 封装" 方案。拒绝单文件版，拒绝黑窗。
实战参考案例（生产级 PySide2 桌面应用，323 MB，含 OpenCV / Playwright）
项目概况
- 总体积: 323 MB
- 打包工具: PyInstaller 4.7 (32位)
- 主要依赖: PySide2 (22.52 MB), OpenCV (62.38 MB), Playwright (76.74 MB)
- Python 版本: Python 3.8 (32位)
- DLL 数量: 71 个，总计 93.23 MB
关键优化策略
- PASS: 使用 32 位 Python → 体积减少 20-30%
- PASS: base_library.zip 压缩标准库 → 0.74 MB
- PASS: 精简模块排除 → 无 pytest/unittest/setuptools
- PASS: 精简 Qt 插件 → 只保留必要插件
体积分布
| 组件 | 体积 | 占比 | 优化建议 |
|---|
| playwright | 76.74 MB | 23.8% | 非必要可移除 |
| OpenCV | 62.38 MB | 19.3% | 用 opencv-python-headless |
| PySide2 | 22.52 MB | 7.0% | 排除 WebEngine/3D/Charts |
| 其他依赖 | 161.36 MB | 49.9% | - |
预期效果对比
| 项目类型 | Nuitka 原始 | 优化后 | 参考项目实测 |
|---|
| Tkinter + 标准库 | 150-250 MB | 80-120 MB | - |
| PyQt/PySide | 200-400 MB | 120-250 MB | 323 MB (含 OpenCV 等) |
| 含 numpy/pandas | 300-600 MB | 180-350 MB | - |
核心工作流 (Workflow) - WARNING: 严格执行
当用户请求打包时，按照以下步骤操作：
步骤 1：强制参数确认（FAIL: 禁止使用默认值）
WARNING: 重要规则：以下所有参数必须逐一向用户确认，禁止自动填充或使用默认值！
必须向用户询问并确认以下信息（等待用户明确回复后才能继续）：
| 参数 | 说明 | 示例 |
|---|
| 软件名称 (App Name) | 软件显示名称 | 红墨批注 |
| 版本号 (Version) | 语义化版本号 | 1.0.0 |
| 发布者/公司名 (Publisher) | 控制面板显示的发布者 | YourCompany |
| 主程序 (Exe Name) | 主可执行文件名 | RedInk.exe |
| 源路径 (Source Dir) | Nuitka dist 文件夹绝对路径 | D:\project\dist |
| 输出路径 (Output Dir) | 安装包生成位置 | D:\project\output |
| 图标路径 (Icon Path) | .ico 文件绝对路径（可选但推荐） | D:\project\icon.ico |
| 官网地址 (URL) | 可选，用于控制面板链接 | https://example.com |
询问模板：
"请提供以下打包参数，我需要您逐一确认：
- 软件名称：
- 版本号：
- 发布者/公司名：
- 主程序文件名（如 xxx.exe）：
- 源路径（Nuitka dist 文件夹）：
- 输出路径（安装包保存位置）：
- 图标路径（.ico 文件，可留空）：
- 官网地址（可留空）：
请逐一填写，或回复"跳过"表示使用空值。"
步骤 2：源文件质量与编译检查（关键）
在生成代码之前，必须向用户发出以下关键确认（因为 Inno Setup 只是打包工具，无法改变程序本身的运行属性）：
"WARNING: 编译参数检查：
- 去黑窗：请确认您的 dist 文件夹是使用
nuitka --windows-console-mode=disable 编译的。（否则安装后依然会有黑框）
- 高性能：请确认是否使用了
--lto=yes。（否则启动速度可能不理想）
- 运行库：请确保 dist 文件夹内已包含必要的 VC++ 运行库，防止在纯净系统上无法运行。
确认源文件已准备好请回复"确认"，否则请先重新编译。"
步骤 3：生成代码
用户确认后，输出包含 完整元数据 和 卸载图标修复 的代码。
Nuitka 极限优化编译（基于 参考项目经验）
一、32 位 vs 64 位选择策略
参考项目使用 32 位 Python 的原因：
| 组件 | 64位体积 | 32位体积 | 节省 |
|---|
| python3x.dll | ~4.5 MB | ~3.8 MB | 15% |
| Qt5Core.dll | ~8 MB | ~5 MB | 37% |
| numpy | ~30 MB | ~20 MB | 33% |
| 总体 | 基准 | -20~30% | - |
推荐使用 32 位条件：
- PASS: 程序内存占用 < 2GB
- PASS: 不处理超大文件（< 2GB）
- PASS: 目标用户是普通办公电脑
32 位编译方法：
py -3.12-32 -m pip install -r requirements.txt
py -3.12-32 -m nuitka --standalone ...你的参数
二、模块排除清单（参考项目验证过的）
安全排除列表（运行时不需要）：
unittest,test,pytest,_pytest,doctest,pdb,pdbpp,
setuptools,pip,distutils,pkg_resources,
email.mime,http.server,xmlrpc,pydoc
预期效果：节省 30-50 MB
三、GUI 框架专用优化
Tkinter 极限优化（推荐，最轻量）
nuitka --standalone --windows-console-mode=disable ^
--lto=yes ^
--jobs=8 ^
--enable-plugin=tk-inter ^
--enable-plugin=anti-bloat ^
--noinclude-pytest-mode=nofollow ^
--noinclude-setuptools-mode=nofollow ^
--nofollow-import-to=unittest,test,pytest,_pytest,doctest,pdb,pdbpp ^
--nofollow-import-to=setuptools,pip,distutils,pkg_resources ^
--nofollow-import-to=email.mime,http.server,xmlrpc,pydoc ^
--python-flag=no_docstrings ^
--output-dir=dist ^
--windows-icon-from-ico=icon.ico ^
--remove-output ^
main.py
预期体积：80-120 MB（优化后）
PyQt5 / PySide2 优化
nuitka --standalone --windows-console-mode=disable ^
--lto=yes ^
--jobs=8 ^
--enable-plugin=pyqt5 ^
--enable-plugin=anti-bloat ^
--noinclude-pytest-mode=nofollow ^
--noinclude-setuptools-mode=nofollow ^
--nofollow-import-to=unittest,test,pytest,_pytest,doctest,pdb ^
--nofollow-import-to=setuptools,pip,distutils,pkg_resources ^
--nofollow-import-to=PyQt5.QtWebEngine,PyQt5.QtWebEngineWidgets ^
--nofollow-import-to=PyQt5.Qt3D,PyQt5.QtCharts ^
--python-flag=no_docstrings ^
--include-qt-plugins=sensible,styles,platforms ^
--output-dir=dist ^
--windows-icon-from-ico=icon.ico ^
--remove-output ^
main.py
预期体积：120-250 MB（优化后）
四、一键编译脚本模板
保存为 build_optimized.bat（项目根目录）：
@echo off
chcp 65001 >nul
setlocal enabledelayedexpansion
echo ========================================
echo Nuitka 极限优化编译（参考 参考项目）
echo ========================================
REM === 配置区域（请修改为你的实际值） ===
set APP_NAME=你的软件名
set MAIN_FILE=main.py
set ICON_FILE=icon.ico
REM === 自动检测 CPU 核心数 ===
REM 用 Windows 自带环境变量（wmic 在 Win11 22H2+ 已移除，探不到会让 --jobs=0 单线程编译）
set CPU_CORES=%NUMBER_OF_PROCESSORS%
if not defined CPU_CORES set CPU_CORES=4
set /a BUILD_JOBS=%CPU_CORES%
REM === 参考项目的模块排除清单 ===
set EXCLUDE_MODULES=unittest,test,pytest,_pytest,doctest,pdb,pdbpp
set EXCLUDE_MODULES=%EXCLUDE_MODULES%,setuptools,pip,distutils,pkg_resources
set EXCLUDE_MODULES=%EXCLUDE_MODULES%,email.mime,http.server,xmlrpc,pydoc
echo.
echo [1/4] 清理旧编译...
if exist dist rd /s /q dist
if exist build rd /s /q build
echo.
echo [2/4] Nuitka 编译中（应用 参考项目优化策略）...
echo - CPU 核心: %CPU_CORES% (使用 %BUILD_JOBS% 线程)
echo - 模块排除: %EXCLUDE_MODULES%
echo.
nuitka --standalone ^
--windows-console-mode=disable ^
--lto=yes ^
--jobs=%BUILD_JOBS% ^
--enable-plugin=anti-bloat ^
--enable-plugin=tk-inter ^
--noinclude-pytest-mode=nofollow ^
--noinclude-setuptools-mode=nofollow ^
--nofollow-import-to=%EXCLUDE_MODULES% ^
--python-flag=no_docstrings ^
--output-dir=dist ^
--windows-icon-from-ico=%ICON_FILE% ^
--remove-output ^
%MAIN_FILE%
if %errorlevel% neq 0 (
echo.
echo [错误] 编译失败！
pause
exit /b 1
)
echo.
echo [3/4] 统计编译结果...
for /f %%a in ('powershell -NoProfile -Command "(Get-ChildItem -LiteralPath 'dist\%APP_NAME%.dist' -Recurse -File | Measure-Object -Property Length -Sum).Sum"') do set TOTAL_SIZE=%%a
set TOTAL_SIZE=%TOTAL_SIZE:,=%
set /a SIZE_MB=%TOTAL_SIZE% / 1048576
echo - 编译后体积: %SIZE_MB% MB
echo.
echo [4/4] 执行瘦身清理（参考 参考项目策略）...
powershell -ExecutionPolicy Bypass -File slim_dist.ps1 -DistPath "dist\%APP_NAME%.dist"
echo.
echo ========================================
echo 编译完成！
echo ========================================
pause
五、dist 瘦身脚本（参考项目级别清理）
保存为 slim_dist.ps1（和 build_optimized.bat 同目录）：
param(
[string]$DistPath
)
$ErrorActionPreference = "Continue" # 不静默吞错：删除失败会显示出来，避免假成功
Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "dist 瘦身清理（参考 参考项目策略）" -ForegroundColor Cyan
