Generating Python Installer

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

1. Confirm build parameters — app name, version, publisher, exe name, source/output dirs, icon. Never auto-fill; ask the user.
2. Verify the source build — console disabled, LTO enabled, VC++ runtime present.
3. Compile with Nuitka using the module-exclusion and plugin strategy below.
4. Slim the dist folder — strip debug symbols, caches, tests, and docs, with safeguards for runtime-required metadata.
5. Analyze DLLs to find and trim the largest dependencies.
6. 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

关键优化策略

1. PASS: 使用 32 位 Python → 体积减少 20-30%
2. PASS: base_library.zip 压缩标准库 → 0.74 MB
3. PASS: 精简模块排除 → 无 pytest/unittest/setuptools
4. 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 |

询问模板： > "请提供以下打包参数，我需要您逐一确认： > 1. 软件名称： > 2. 版本号： > 3. 发布者/公司名： > 4. 主程序文件名（如 xxx.exe）： > 5. 源路径（Nuitka dist 文件夹）： > 6. 输出路径（安装包保存位置）： > 7. 图标路径（.ico 文件，可留空）： > 8. 官网地址（可留空）： > > 请逐一填写，或回复"跳过"表示使用空值。"

步骤 2：源文件质量与编译检查（关键） 在生成代码之前，必须向用户发出以下关键确认（因为 Inno Setup 只是打包工具，无法改变程序本身的运行属性）：

> "WARNING: 编译参数检查： > 1. 去黑窗：请确认您的 dist 文件夹是使用 nuitka --windows-console-mode=disable 编译的。（否则安装后依然会有黑框） > 2. 高性能：请确认是否使用了 --lto=yes。（否则启动速度可能不理想） > 3. 运行库：请确保 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: 程序内存占用 nul

setlocal enabledelayedexpansion

echo ======================================== echo Nuitka 极限优化编译（参考 参考项目） echo ========================================

REM === 配置区域（请修改为你的实际值） === set APPNAME=你的软件名 set MAINFILE=main.py set ICON_FILE=icon.ico

REM === 自动检测 CPU 核心数 === REM 用 Windows 自带环境变量（wmic 在 Win11 22H2+ 已移除，探不到会让 --jobs=0 单线程编译） set CPUCORES=%NUMBEROFPROCESSORS% if not defined CPUCORES set CPUCORES=4 set /a BUILDJOBS=%CPU_CORES%

REM === 参考项目的模块排除清单 === set EXCLUDEMODULES=unittest,test,pytest,pytest,doctest,pdb,pdbpp set EXCLUDEMODULES=%EXCLUDEMODULES%,setuptools,pip,distutils,pkgresources set EXCLUDEMODULES=%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 核心: %CPUCORES% (使用 %BUILDJOBS% 线程) echo - 模块排除: %EXCLUDE_MODULES% echo.

nuitka --standalone ^ --windows-console-mode=disable ^ --lto=yes ^ --jobs=%BUILDJOBS% ^ --enable-plugin=anti-bloat ^ --enable-plugin=tk-inter ^ --noinclude-pytest-mode=nofollow ^ --noinclude-setuptools-mode=nofollow ^ --nofollow-import-to=%EXCLUDEMODULES% ^ --python-flag=nodocstrings ^ --output-dir=dist ^ --windows-icon-from-ico=%ICONFILE% ^ --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\%APPNAME%.dist' -Recurse -File | Measure-Object -Property Length -Sum).Sum"') do set TOTALSIZE=%%a set TOTALSIZE=%TOTALSIZE:,=% set /a SIZEMB=%TOTALSIZE% / 1048576 echo - 编译后体积: %SIZE_MB% MB

echo. echo [4/4] 执行瘦身清理（参考 参考项目策略）... powershell -ExecutionPolicy Bypass -File slimdist.ps1 -DistPath "dist\%APPNAME%.dist"

echo. echo ======================================== echo 编译完成！ echo ======================================== pause

### 五、dist 瘦身脚本（参考项目级别清理）

**保存为 `slim_dist.ps1`（和 build_optimized.bat 同目录）**：

```powershell
param(
    [string]$DistPath
)

$ErrorActionPreference = "Continue"  # 不静默吞错：删除失败会显示出来，避免假成功

Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "dist 瘦身清理（参考 参考项目策略）" -ForegroundColor Cyan
Write-Host "========================================" -ForegroundColor Cyan

if (-not (Test-Path $DistPath)) {
    Write-Host "[错误] 找不到目录: $DistPath" -ForegroundColor Red
    exit 1
}

# 统计初始体积
$InitialSize = (Get-ChildItem -Path $DistPath -Recurse -File | Measure-Object -Property Length -Sum).Sum / 1MB
Write-Host "`n初始体积: $([math]::Round($InitialSize, 2)) MB" -ForegroundColor Yellow

# 参考项目特征：没有 .pdb, .pyi, __pycache__, test 等
Write-Host "`n[应用 参考项目的清理策略...]" -ForegroundColor Green

# 1. 删除调试符号
Write-Host "`n[1/7] 删除 .pdb 调试符号..." -ForegroundColor Green
$pdbFiles = Get-ChildItem -Path $DistPath -Recurse -Include *.pdb -File
$pdbSize = ($pdbFiles | Measure-Object -Property Length -Sum).Sum / 1MB
if ($pdbFiles.Count -gt 0) {
    $pdbFiles | Remove-Item -Force
    Write-Host "  删除 $($pdbFiles.Count) 个文件，节省 $([math]::Round($pdbSize, 2)) MB"
} else {
    Write-Host "  未发现 .pdb 文件（已优化）" -ForegroundColor Gray
}

# 2. 删除类型提示
Write-Host "`n[2/7] 删除 .pyi 类型提示..." -ForegroundColor Green
$pyiFiles = Get-ChildItem -Path $DistPath -Recurse -Include *.pyi -File
$pyiSize = ($pyiFiles | Measure-Object -Property Length -Sum).Sum / 1MB
if ($pyiFiles.Count -gt 0) {
    $pyiFiles | Remove-Item -Force
    Write-Host "  删除 $($pyiFiles.Count) 个文件，节省 $([math]::Round($pyiSize, 2)) MB"
} else {
    Write-Host "  未发现 .pyi 文件（已优化）" -ForegroundColor Gray
}

# 3. 删除 __pycache__
Write-Host "`n[3/7] 删除 __pycache__ 缓存..." -ForegroundColor Green
$pycacheDirs = Get-ChildItem -Path $DistPath -Recurse -Directory -Filter "__pycache__"
$pycacheSize = 0
foreach ($dir in $pycacheDirs) {
    $size = (Get-ChildItem -Path $dir.FullName -Recurse -File | Measure-Object -Property Length -Sum).Sum
    $pycacheSize += $size
    Remove-Item -Path $dir.FullName -Recurse -Force
}
if ($pycacheDirs.Count -gt 0) {
    Write-Host "  删除 $($pycacheDirs.Count) 个目录，节省 $([math]::Round($pycacheSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现 __pycache__（已优化）" -ForegroundColor Gray
}

# 4. 删除测试目录
Write-Host "`n[4/7] 删除 test/tests 测试目录..." -ForegroundColor Green
$testDirs = Get-ChildItem -Path $DistPath -Recurse -Directory | Where-Object { $_.Name -match '^tests?$' }
$testSize = 0
foreach ($dir in $testDirs) {
    $size = (Get-ChildItem -Path $dir.FullName -Recurse -File | Measure-Object -Property Length -Sum).Sum
    $testSize += $size
    Remove-Item -Path $dir.FullName -Recurse -Force
}
if ($testDirs.Count -gt 0) {
    Write-Host "  删除 $($testDirs.Count) 个目录，节省 $([math]::Round($testSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现测试目录（已优化）" -ForegroundColor Gray
}

# 5. 删除文档和示例
Write-Host "`n[5/7] 删除 docs/examples 文档目录..." -ForegroundColor Green
$docDirs = Get-ChildItem -Path $DistPath -Recurse -Directory | Where-Object { $_.Name -match '^(docs|examples|samples|demo)$' }
$docSize = 0
foreach ($dir in $docDirs) {
    $size = (Get-ChildItem -Path $dir.FullName -Recurse -File | Measure-Object -Property Length -Sum).Sum
    $docSize += $size
    Remove-Item -Path $dir.FullName -Recurse -Force
}
if ($docDirs.Count -gt 0) {
    Write-Host "  删除 $($docDirs.Count) 个目录，节省 $([math]::Round($docSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现文档目录（已优化）" -ForegroundColor Gray
}

# 6. 删除 .pyc 文件
Write-Host "`n[6/7] 删除 .pyc 字节码..." -ForegroundColor Green
$pycFiles = Get-ChildItem -Path $DistPath -Recurse -Include *.pyc -File
$pycSize = ($pycFiles | Measure-Object -Property Length -Sum).Sum / 1MB
if ($pycFiles.Count -gt 0) {
    $pycFiles | Remove-Item -Force
    Write-Host "  删除 $($pycFiles.Count) 个文件，节省 $([math]::Round($pycSize, 2)) MB"
} else {
    Write-Host "  未发现 .pyc 文件（已优化）" -ForegroundColor Gray
}

# 7. 精简 .dist-info 元数据
Write-Host "`n[7/7] 精简 .dist-info 元数据..." -ForegroundColor Green
$distInfoDirs = Get-ChildItem -Path $DistPath -Recurse -Directory -Filter "*.dist-info"
$removedCount = 0
$removedSize = 0
foreach ($infoDir in $distInfoDirs) {
    # 仅删安装期记账文件；保留 METADATA 与 entry_points.txt（运行期被 importlib.metadata 读取，删除会破坏插件发现）
    $filesToRemove = @("RECORD", "INSTALLER", "direct_url.json")
    foreach ($fileName in $filesToRemove) {
        $file = Join-Path $infoDir.FullName $fileName
        if (Test-Path $file) {
            $size = (Get-Item $file).Length
            $removedSize += $size
            Remove-Item $file -Force
            $removedCount++
        }
    }
}
if ($removedCount -gt 0) {
    Write-Host "  删除 $removedCount 个元数据文件，节省 $([math]::Round($removedSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现可清理的元数据（已优化）" -ForegroundColor Gray
}

# 统计最终体积
$FinalSize = (Get-ChildItem -Path $DistPath -Recurse -File | Measure-Object -Property Length -Sum).Sum / 1MB
$SavedSize = $InitialSize - $FinalSize
$SavedPercent = if ($InitialSize -gt 0) { ($SavedSize / $InitialSize) * 100 } else { 0 }

Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "清理完成！" -ForegroundColor Green
Write-Host "========================================" -ForegroundColor Cyan
Write-Host "初始体积: $([math]::Round($InitialSize, 2)) MB" -ForegroundColor Yellow
Write-Host "最终体积: $([math]::Round($FinalSize, 2)) MB" -ForegroundColor Green
Write-Host "节省空间: $([math]::Round($SavedSize, 2)) MB ($([math]::Round($SavedPercent, 1))%)" -ForegroundColor Cyan
Write-Host "========================================`n" -ForegroundColor Cyan

# 对比 参考项目
Write-Host "[对比参考]" -ForegroundColor Yellow
Write-Host "参考项目总体积: 323 MB (包含 PyQt, OpenCV, Playwright 等重量级库)" -ForegroundColor Gray
Write-Host "如果你的项目是纯 Tkinter + 标准库，目标应该在 80-150 MB" -ForegroundColor Gray

预期效果：节省 15-30% 体积

六、DLL 依赖分析工具

保存为 analyze_dlls.py（用于找出体积大户）：

"""
DLL 依赖分析工具
参考 参考项目的 DLL 管理策略，帮助识别体积大户和优化建议
"""
import sys
from pathlib import Path

def analyze_dlls(dist_path: str):
    """分析 dist 目录中的 DLL 依赖"""
    dist_dir = Path(dist_path)

    if not dist_dir.exists():
        print(f"[错误] 目录不存在: {dist_path}")
        return

    print("=" * 70)
    print("DLL 依赖分析（参考 参考项目策略）")
    print("=" * 70)

    # 收集所有 DLL
    dll_files = list(dist_dir.rglob("*.dll"))

    if not dll_files:
        print("\n未发现 DLL 文件")
        return

    # 按大小排序
    dll_data = [(dll, dll.stat().st_size) for dll in dll_files]
    dll_data.sort(key=lambda x: x[1], reverse=True)

    total_size = sum(size for _, size in dll_data)

    print(f"\n总 DLL 数量: {len(dll_files)}")
    print(f"总 DLL 体积: {total_size / 1024 / 1024:.2f} MB\n")

    # 参考项目对比
    print("[对比参考] 参考项目的 DLL 情况:")
    print("  - 总数量: 71 个")
    print("  - 总体积: 93.23 MB")
    print("  - 最大的: libopenblas (26.85 MB), opengl32sw (15.25 MB)\n")

    # 分析大于 3MB 的 DLL
    large_dlls = [(dll, size) for dll, size in dll_data if size > 3 * 1024 * 1024]

    if large_dlls:
        print("=" * 70)
        print("WARNING:  大于 3MB 的 DLL（需重点关注）")
        print("=" * 70)

        for dll, size in large_dlls:
            size_mb = size / 1024 / 1024
            relative_path = dll.relative_to(dist_dir)
            name_lower = dll.name.lower()

            print(f"\n{size_mb:8.2f} MB  {dll.name}")
            print(f"           位置: {relative_path.parent}")

            # 优化建议
            suggestions = get_optimization_suggestion(name_lower)
            if suggestions:
                for suggestion in suggestions:
                    print(f"            {suggestion}")

    # 检查冗余 DLL
    print("\n" + "=" * 70)
    print(" 冗余检查")
    print("=" * 70)

    # 检查调试版本
    debug_dlls = [dll for dll, _ in dll_data if dll.stem.endswith('d')]
    if debug_dlls:
        print(f"\nWARNING:  发现 {len(debug_dlls)} 个调试版本 DLL（可以删除）:")
        for dll in debug_dlls:
            print(f"  - {dll.name}")
    else:
        print("\nPASS: 未发现调试版本 DLL（已优化）")

    # VC++ Runtime
    vc_runtimes = [dll for dll, _ in dll_data if 'vcruntime' in dll.name.lower() or 'msvcp' in dll.name.lower()]
    if vc_runtimes:
        print(f"\n[VC++ Runtime 库] 发现 {len(vc_runtimes)} 个:")
        for dll in vc_runtimes:
            size_mb = dll.stat().st_size / 1024 / 1024
            print(f"  - {dll.name} ({size_mb:.2f} MB)")
        print("   这些是必需的，参考项目也包含了这些文件")

    # 全部 DLL 列表
    print("\n" + "=" * 70)
    print(" 完整 DLL 列表（按体积排序，前 20）")
    print("=" * 70)
    print(f"\n{'体积 (MB)':>10}  {'文件名': 20:
        remaining_size = sum(size for _, size in dll_data[20:]) / 1024 / 1024
        print(f"... 还有 {len(dll_data) - 20} 个 DLL，共 {remaining_size:.2f} MB")

def get_optimization_suggestion(dll_name: str) -> list:
    """根据 DLL 名称给出优化建议"""
    suggestions = []

    if "openblas" in dll_name or "mkl" in dll_name:
        suggestions.append("数学运算库，参考项目的 libopenblas 有 26.85 MB")
        suggestions.append("如不需要高性能计算可考虑轻量版")

    elif "opencv" in dll_name or "ffmpeg" in dll_name:
        suggestions.append("OpenCV 相关，参考项目的 opencv_videoio_ffmpeg 有 18.48 MB")
        suggestions.append("考虑用 opencv-python-headless")

    elif "qt5" in dll_name or "qt6" in dll_name or "pyside" in dll_name:
        suggestions.append("Qt 库，参考项目的 Qt5Core 有 5.13 MB")
        suggestions.append("可排除不需要的模块（WebEngine, 3D, Charts）")

    elif "opengl" in dll_name and "sw" in dll_name:
        suggestions.append("OpenGL 软件渲染器，参考项目保留了 15.25 MB")
        suggestions.append("通常可以删除（使用硬件渲染）")

    elif "d3dcompiler" in dll_name:
        suggestions.append("DirectX 编译器，参考项目有 3.53 MB")

    elif "

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [affaan-m](https://github.com/affaan-m)
- **Source:** [affaan-m/ECC](https://github.com/affaan-m/ECC)
- **License:** MIT
- **Homepage:** https://ecc.tools

Install and usage instructions live in the source repository linked above.