Overview

PIW (Python Intelligent Wrapper) creates native macOS .app bundles from any Python application in one step. Point it at your project directory, click Build — you get a working .app bundle with proper Info.plist, icon, launcher, and all dependencies resolved.

The problem: Packaging Python desktop apps for macOS is painful. Existing tools (PyInstaller, py2app, Briefcase) produce bloated bundles, break on PyQt6, require complex spec files, and frequently fail on Apple Silicon. Developers spend more time fighting the packager than building their app.

The solution: PIW creates native macOS .app bundles from any Python application in one step. Point it at your project directory, click Build — you get a working .app bundle with proper Info.plist, icon, launcher, and all dependencies resolved. No spec files, no hidden import debugging, no bloat.

Key Features

• One-click bundling - GUI or CLI, point at any Python project and get a .app bundle
• Automatic venv detection - Finds .venv/venv, detects Python version, copies site-packages
• Standalone mode - Optionally embeds the entire Python framework for zero-dependency distribution
• Source protection - Bytecode-only builds strip all .py source; optional obfuscation removes docstrings, asserts, and randomizes timestamps
• Smart entry point detection - Finds main.py, app.py, run.py, start.py, or __main__.py automatically
• Proper macOS integration - Generates Info.plist, PkgInfo, icon handling, stderr logging to ~/.appname/logs/
• pyproject.toml plist extras - Declare [tool.piw.plist] keys (e.g., NSMicrophoneUsageDescription) and they merge into Info.plist automatically
• Installer creation - Generates distributable Install-AppName.app packages for end users (no Terminal required)
• Build tracking - SQLite database records every build (version, size, settings, timestamps) for audit and history
• Version management - Integrated version_info system with semantic versioning and auto-incrementing build numbers
• lib_deps auto-bundling - Automatically packages external library dependencies when present
• Apple Silicon native - Built for and tested on ARM64 macOS (Homebrew Python paths)

What Makes It Different

Feature	PIW	PyInstaller	py2app	Briefcase
PyQt6 support	Native, tested	Fragile hooks	Broken on Qt6	Indirect
Apple Silicon	First-class	Patchy	Untested	Partial
Config needed	Zero (or pyproject.toml)	.spec file	setup.py	pyproject.toml + template
Bundle size	Minimal (copies only what’s needed)	Bloated (kitchen-sink)	Medium	Large (full stdlib)
Source protection	Bytecode + obfuscation built-in	Limited	None	None
Installer generation	Built-in	Requires separate tool	None	Platform-specific
Build history	SQLite tracker	None	None	None
GUI	Full PyQt6 interface	CLI only	CLI only	CLI only

Key differentiator: PIW doesn’t try to reverse-engineer imports or trace dependencies. It copies your venv’s site-packages directly — if your app runs in the venv, the bundle works. This eliminates the entire class of “missing hidden import” bugs that plague PyInstaller.

Use Cases

Independent Developers

Ship Python desktop apps on macOS without requiring users to install Python, pip, or manage dependencies. One .app file, drag to Applications, done.

PyQt6/PySide6 Projects

Reliable packaging where alternatives consistently fail. PyInstaller’s Qt6 hooks break regularly, py2app doesn’t support Qt6 properly. PIW works because it doesn’t rely on hooks — it copies your working venv.

Internal Tool Distribution

Deliver tools to teams without Python knowledge. No “install Python 3.13.1 then pip install -r requirements.txt” — just double-click the app.

Source Code Protection

Distribute apps without exposing source code. Bytecode-only builds + optional obfuscation (docstring/assert removal, timestamp randomization) make reverse engineering harder.

Consulting Deliverables

Ship client applications as professional .app bundles with custom icons, proper metadata, and installer packages. No Terminal required for end users.

Architecture

┌──────────────────────────────────────┐
│      PIW GUI/CLI                     │
│      (PyQt6)                         │
└──────────┬───────────────────────────┘
           │
    ┌──────▼─────────────────────┐
    │  Bundle Builder            │
    │  • Detect venv/Python      │
    │  • Copy site-packages      │
    │  • Generate Info.plist     │
    │  • Create launcher script  │
    │  • Package .app structure  │
    └──────┬─────────────────────┘
           │
    ┌──────▼─────────────────────┐
    │  Build Database (SQLite)   │
    │  • Version history         │
    │  • Build settings          │
    │  • Project config          │
    └────────────────────────────┘

PIW analyzes your project, copies your working venv, generates native macOS metadata, and creates a properly structured .app bundle. Optional standalone mode embeds Python framework for zero-dependency distribution.

Production Status

PIW v1.0.0, Build 2 — Production-ready, self-hosted (PIW bundles itself).

Currently packages 6+ Silver Wizard production applications:

• IATV (Independent Agent Terminal Viewer)
• CONF (Multi-agent conferencing framework)
• Mac Retriever (Gmail client + file manager)
• CMC (Claude Code MCP Manager)
• BE_JOBS (Background job manager)
• PIW itself (dogfooded)

Tech Stack

• Python 3.13 - Core application
• PyQt6 - GUI framework
• SQLite - Build history and project configuration
• macOS 11.0+ - Apple Silicon native (ARM64)
• sw2-lib - Internal utilities
• Zero external runtime deps - Bundled apps have no dependencies

Best Practices

1. Test in venv first - If your app runs in the venv, PIW’s bundle will work
2. Use pyproject.toml for metadata - Declare Info.plist keys in [tool.piw.plist]
3. Enable standalone mode for distribution - Embed Python framework so users don’t need Python installed
4. Version management - Let PIW auto-increment build numbers, use semantic versioning
5. Build history - Use SQLite tracker to audit builds and settings over time

Licensing

PIW is production infrastructure available for licensing to organizations and independent developers packaging Python apps for macOS.

Contact: silver.wizard001@proton.me for licensing inquiries.

Documentation

• Getting Started Guide
• Configuration Reference
• Build Options
• Troubleshooting

Support

• Email: support@silverwizard.dev
• Licensing: silver.wizard001@proton.me