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

• "Package this PySide2 project into the smallest commercial installer with Nuitka" → run the full workflow: recommend 32-bit, exclude WebEngine/3D/Charts, slim dist, package with Inno Setup.
• "My exe is 400 MB, how to slim it down to half" → analyze DLLs, switch to opencv-python-headless, drop opengl32sw, apply dist slimming.
• "Can't open after installation on a clean system" → ensure the matching-arch VC++ redistributable is bundled in the Inno Setup script.

---

Core Philosophy

Adhere to the "Nuitka folder mode (dist) + Inno Setup packaging" approach. Reject single-file builds and console windows.

---

Practical Reference Case (Production PySide2 Desktop App, 323 MB, with OpenCV / Playwright)

Project Overview

• Total size: 323 MB
• Packaging tool: PyInstaller 4.7 (32-bit)
• Main dependencies: PySide2 (22.52 MB), OpenCV (62.38 MB), Playwright (76.74 MB)
• Python version: Python 3.8 (32-bit)
• DLL count: 71, totaling 93.23 MB

Key Optimization Strategies

1. PASS: Use 32-bit Python → reduces size by 20-30%
2. PASS: Compress standard library with base_library.zip → 0.74 MB
3. PASS: Exclude redundant modules → no pytest/unittest/setuptools
4. PASS: Trim Qt plugins → keep only necessary plugins

Size Distribution

Component	Size	Percentage	Optimization Suggestion
playwright	76.74 MB	23.8%	Remove if not needed
OpenCV	62.38 MB	19.3%	Use opencv-python-headless
PySide2	22.52 MB	7.0%	Exclude WebEngine/3D/Charts
Other dependencies	161.36 MB	49.9%	-

Expected Size Comparison

Project Type	Nuitka Original	Optimized	Reference Project Actual
Tkinter + stdlib	150-250 MB	80-120 MB	-
PyQt/PySide	200-400 MB	120-250 MB	323 MB (including OpenCV, etc.)
With numpy/pandas	300-600 MB	180-350 MB	-

---

Core Workflow - WARNING: Strictly Follow

When the user requests packaging, follow these steps:

Step 1: Mandatory Parameter Confirmation (FAIL: Do not use defaults)

WARNING: Important Rule: All the following parameters must be confirmed with the user one by one. Never auto-fill or use default values!

You must ask the user and confirm the following information (wait for the user's explicit reply before proceeding):

Parameter	Description	Example
App Name	Software display name	RedInk Annotation
Version	Semantic version number	1.0.0
Publisher	Publisher name shown in Control Panel	YourCompany
Exe Name	Main executable filename	RedInk.exe
Source Dir	Absolute path to the Nuitka dist folder	D:\project\dist
Output Dir	Location for the installer package	D:\project\output
Icon Path	Absolute path to the .ico file (optional but recommended)	D:\project\icon.ico
URL	Optional, for Control Panel link	https://example.com

Query Template:

"Please provide the following packaging parameters, I need you to confirm each one:

1. App Name:
2. Version:
3. Publisher:
4. Main executable filename (e.g., xxx.exe):
5. Source Dir (Nuitka dist folder):
6. Output Dir (installer save location):
7. Icon Path (.ico file, can be left blank):
8. URL (can be left blank):

Please fill in one by one, or reply 'Skip' to use empty values."

Step 2: Source File Quality and Compilation Check (Critical) Before generating the code, you must issue the following critical confirmation to the user (because Inno Setup is just a packaging tool and cannot change the runtime properties of the program itself):

"WARNING: Compilation Parameter Check:

1. Remove Console Window: Please confirm your dist folder was compiled using nuitka --windows-console-mode=disable. (Otherwise, a console window will still appear after installation)
2. High Performance: Please confirm you used --lto=yes. (Otherwise, startup speed may be suboptimal)
3. Runtime Library: Please ensure the necessary VC++ runtime libraries are included in your dist folder to prevent issues on clean systems.

Please reply 'Confirmed' when the source files are ready, otherwise please recompile first."

Step 3: Generate Code After the user confirms, output the code with full metadata and uninstall icon fix.

---

Nuitka Extreme Optimized Compilation (Based on Reference Project Experience)

I. 32-bit vs 64-bit Selection Strategy

Reason for using 32-bit Python in the reference project:

Component	64-bit Size	32-bit Size	Savings
python3x.dll	~4.5 MB	~3.8 MB	15%
Qt5Core.dll	~8 MB	~5 MB	37%
numpy	~30 MB	~20 MB	33%
Total	Baseline	-20~30%	-

Conditions for recommending 32-bit:

• PASS: Program memory usage < 2GB
• PASS: Not processing very large files (< 2GB)
• PASS: Target users are on standard office computers

How to compile with 32-bit:

# 1. Install 32-bit Python (can coexist with 64-bit)
# Download: https://www.python.org/downloads/windows/

# 2. Install dependencies with 32-bit Python
py -3.12-32 -m pip install -r requirements.txt

# 3. Compile with 32-bit Python
py -3.12-32 -m nuitka --standalone ...your parameters

II. Module Exclusion List (Verified by Reference Project)

Safe exclusions (not needed at runtime):

unittest,test,pytest,_pytest,doctest,pdb,pdbpp,
setuptools,pip,distutils,pkg_resources,
email.mime,http.server,xmlrpc,pydoc

Expected Savings: 30-50 MB

III. GUI Framework-Specific Optimizations

Tkinter Extreme Optimization (Recommended, Lightest)

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

Expected Size: 80-120 MB (after optimization)

PyQt5 / PySide2 Optimization

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

Expected Size: 120-250 MB (after optimization)

IV. One-Click Compilation Script Template

Save as build_optimized.bat (project root directory):

@echo off
chcp 65001 >nul
setlocal enabledelayedexpansion

echo ========================================
echo Nuitka Extreme Optimized Compilation (Reference: Reference Project)
echo ========================================

REM === Configuration Area (Modify to your actual values) ===
set APP_NAME=YourAppName
set MAIN_FILE=main.py
set ICON_FILE=icon.ico

REM === Auto-detect CPU Cores ===
REM Use Windows built-in environment variable (wmic is removed in Win11 22H2+, not detecting will make --jobs=0 single-threaded)
set CPU_CORES=%NUMBER_OF_PROCESSORS%
if not defined CPU_CORES set CPU_CORES=4
set /a BUILD_JOBS=%CPU_CORES%

REM === Reference Project's Module Exclusion List ===
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] Cleaning old builds...
if exist dist rd /s /q dist
if exist build rd /s /q build

echo.
echo [2/4] Running Nuitka compilation (Applying Reference Project Optimization Strategies)...
echo - CPU Cores: %CPU_CORES% (Using %BUILD_JOBS% threads)
echo - Module Exclusion: %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 [ERROR] Compilation failed!
    pause
    exit /b 1
)

echo.
echo [3/4] Counting compilation results...
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 - Build size: %SIZE_MB% MB

echo.
echo [4/4] Running slimming cleanup (Applying Reference Project Strategy)...
powershell -ExecutionPolicy Bypass -File slim_dist.ps1 -DistPath "dist\%APP_NAME%.dist"

echo.
echo ========================================
echo Compilation Complete!
echo ========================================
pause

V. dist Slimming Script (Reference Project Level Cleanup)

Save as slim_dist.ps1 (in the same directory as build_optimized.bat):

param(
    [string]$DistPath
)

$ErrorActionPreference = "Continue"  # Don't silently swallow errors: show deletion failures to avoid false success

Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "dist Slimming Cleanup (Reference Project Strategy)" -ForegroundColor Cyan
Write-Host "========================================" -ForegroundColor Cyan

if (-not (Test-Path $DistPath)) {
    Write-Host "[ERROR] Directory not found: $DistPath" -ForegroundColor Red
    exit 1
}

# Count initial size
$InitialSize = (Get-ChildItem -Path $DistPath -Recurse -File | Measure-Object -Property Length -Sum).Sum / 1MB
Write-Host "`nInitial size: $([math]::Round($InitialSize, 2)) MB" -ForegroundColor Yellow

# Reference project characteristics: no .pdb, .pyi, __pycache__, test, etc.
Write-Host "`n[Applying Reference Project Cleanup Strategy...]" -ForegroundColor Green

# 1. Delete debug symbols
Write-Host "`n[1/7] Deleting .pdb debug symbols..." -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 "  Deleted $($pdbFiles.Count) files, saved $([math]::Round($pdbSize, 2)) MB"
} else {
    Write-Host "  No .pdb files found (already optimized)" -ForegroundColor Gray
}

# 2. Delete type hints
Write-Host "`n[2/7] Deleting .pyi type hints..." -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 "  Deleted $($pyiFiles.Count) files, saved $([math]::Round($pyiSize, 2)) MB"
} else {
    Write-Host "  No .pyi files found (already optimized)" -ForegroundColor Gray
}

# 3. Delete __pycache__
Write-Host "`n[3/7] Deleting __pycache__ cache..." -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 "  Deleted $($pycacheDirs.Count) directories, saved $([math]::Round($pycacheSize / 1MB, 2)) MB"
} else {
    Write-Host "  No __pycache__ found (already optimized)" -ForegroundColor Gray
}

# 4. Delete test directories
Write-Host "`n[4/7] Deleting test/tests directories..." -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 "  Deleted $($testDirs.Count) directories, saved $([math]::Round($testSize / 1MB, 2)) MB"
} else {
    Write-Host "  No test directories found (already optimized)" -ForegroundColor Gray
}

# 5. Delete documentation and examples
Write-Host "`n[5/7] Deleting docs/examples directories..." -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 "  Deleted $($docDirs.Count) directories, saved $([math]::Round($docSize / 1MB, 2)) MB"
} else {
    Write-Host "  No documentation directories found (already optimized)" -ForegroundColor Gray
}

# 6. Delete .pyc files
Write-Host "`n[6/7] Deleting .pyc bytecode..." -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 "  Deleted $($pycFiles.Count) files, saved $([math]::Round($pycSize, 2)) MB"
} else {
    Write-Host "  No .pyc files found (already optimized)" -ForegroundColor Gray
}

# 7. Trim .dist-info metadata
Write-Host "`n[7/7] Trimming .dist-info metadata..." -ForegroundColor Green
$distInfoDirs = Get-ChildItem -Path $DistPath -Recurse -Directory -Filter "*.dist-info"
$removedCount = 0
$removedSize = 0
foreach ($infoDir in $distInfoDirs) {
    # Only delete installation accounting files; keep METADATA and entry_points.txt (runtime-read by importlib.metadata, deleting them breaks plugin discovery)
    $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 "  Deleted $removedCount metadata files, saved $([math]::Round($removedSize / 1MB, 2)) MB"
} else {
    Write-Host "  No cleanable metadata found (already optimized)" -ForegroundColor Gray
}

# Count final size
$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 "Cleanup Complete!" -ForegroundColor Green
Write-Host "========================================" -ForegroundColor Cyan
Write-Host "Initial size: $([math]::Round($InitialSize, 2)) MB" -ForegroundColor Yellow
Write-Host "Final size: $([math]::Round($FinalSize, 2)) MB" -ForegroundColor Green
Write-Host "Space saved: $([math]::Round($SavedSize, 2)) MB ($([math]::Round($SavedPercent, 1))%)" -ForegroundColor Cyan
Write-Host "========================================" -ForegroundColor Cyan

---

Inno Setup Script Generation

This skill is also responsible for generating the final Inno Setup script (installer.iss) and optionally compiling it to produce the smallest possible installer. The generated script will include:

• Full metadata: AppName, AppVersion, AppPublisher, AppURL (if provided)
• Clean uninstall: Uses UninstallFilesDir and UninstallDisplayIcon to ensure a residue-free uninstall
• Arch-matched VC++ redistributable: Detects whether the built files are 32-bit or 64-bit and includes the correct redistributable installer
• LZMA2 ultra compression: For the smallest possible installer size

(Note: The actual Inno Setup script generation is triggered in a separate command after the user confirms the parameters. The details of the script will be provided upon request.)