fspack
One-command Python packaging — produce executables and installers.
fspack turns your Python project into a distributable desktop app with one command.
No source code changes needed — fsp b produces .exe, fsp p produces a Windows
installer or Linux .deb. Auto-dependency inference, smart wheel slimming,
pre-compiled bytecode, out of the box.
✨ Highlights
- One-command workflow:
fsp bbuilds,fsp ppackages — cargo-style two-letter shortcuts - Zero config: AST-based
importanalysis infers dependencies automatically - Smart slimming: Strip unused wheel sub-modules (Qt apps drop from 300MB → 80MB)
- Cross-platform: Windows NSIS
.exe, Linux.deb+.tar.gz, macOS.pkg+.dmg - Win7 compatible: Unique API shim DLLs — PyInstaller/Nuitka cannot do this
- Offline mode:
FSPACK_OFFLINE=1for air-gapped CI/packaging machines - Monorepo-friendly:
fsp b -Rrecursively builds all sub-projects - Nuitka boost:
--nuitkaflag for 30-50% faster startup
⚡ 30-Second Quick Start
pip install fspack
cd your-project # Python project with pyproject.toml
fsp b # Produces dist/your-app.exe
fsp p # Produces dist/release/your-app-setup.exe
That's it. Your Python project is now a distributable desktop app that others can double-click to run — no Python installation required on the user's machine.
What It Looks Like
Click the thumbnail above to play a real recording of fsp init →
fsp b → fsp p. The raw recording is in
docs/assets/demo.cast (asciinema v2 NDJSON).
🚀 Start From a Template
No project yet? Scaffold one from 18 built-in templates covering CLI, GUI, games, science, and web scenarios:
fsp init my-app --template pyside2 # Create PySide2 GUI project
fsp init --list # List all available templates
Each template generates a packable project skeleton (pyproject.toml + entry script).
cd in and run fsp b immediately.
🔄 Competitor Comparison
| Feature | fspack | PyInstaller | Nuitka | cx_Freeze | Briefcase |
|---|---|---|---|---|---|
| One-command build | ✅ fsp b |
pyinstaller --onefile |
python -m nuitka |
cxfreeze |
briefcase build |
| Auto-dependency inference | AST closure | Hooks + hidden imports | AST + runtime tracer | Config file | Manual |
| Smart slimming | By import closure | Basic strip | None | None | None |
| Cross-platform installers | Win/Linux/macOS | Executable only | Executable only | Executable only | Win/macOS |
| Win7 compatibility | ✅ API shim | ❌ | ❌ | ❌ | ❌ |
| Offline packaging | ✅ | ❌ | ❌ | ❌ | ❌ |
| Multi-entry monorepo | ✅ -R |
Multiple commands | Multiple commands | Multiple commands | ❌ |
| Nuitka acceleration | --nuitka |
❌ | Nuitka only | ❌ | ❌ |
📦 Installation
pip install fspack
Or with uv:
uv add fspack
📖 Usage
Single Project Build
In your Python project root (with pyproject.toml):
# 1. Build: produces dist/<name>.exe and dist/runtime/
fsp b
# 2. Run and verify the packaged app
fsp r
# 3. Create installer: produces dist/release/<name>-setup.exe
fsp p
# 4. Clean up dist/
fsp c
Specify project directory and options:
fsp b /path/to/project --mirror aliyun --py-version 3.11.9 --target windows
Recursive Monorepo Build
fsp b -R ./workspace # Recursively build all sub-projects
fsp p -R ./monorepo # Recursively package all sub-projects
Multi-Entry Projects
Declare multiple entry points via standard PEP 621 [project.scripts]:
fsp b # Build all declared entry executables
fsp r --entry cli # Run the cli entry
fsp r --entry gui # Run the gui entry
📋 Command Reference
Global options: -V/--version shows version, -v/--verbose enables DEBUG logging.
| Command | Alias | Description |
|---|---|---|
fsp build |
fsp b |
Build project — produce executables and runtime |
fsp run |
fsp r |
Run packaged app (native binary directly; .exe via wine on Linux) |
fsp clean |
fsp c |
Clean dist/ directory |
fsp package |
fsp p |
Create installers (Windows NSIS / Linux .deb + tar.gz / macOS pkg + dmg) |
fsp init |
fsp i |
Scaffold new project from templates (18 available) |
fsp doctor |
fsp d |
Environment diagnostics — check toolchain availability |
fsp manifest |
fsp m |
Artifact manifest generation and diff (generate/diff) |
fsp cache |
— | Cache health check and cleanup (corrupted/stale/orphaned) |
fsp b [project] [--mirror] [--py-version] [--target] [--nuitka] [-R] [--dry-run] [--profile] ...
fsp r [project] [--entry <name>] [--debug] [--profile] [-- <args>...]
fsp p [project] [--no-build] [--format <auto|zip|nsis|tar.gz|deb|pkg|dmg|all>] [-R]
fsp init [name] [--template <id>] [--list]
fsp manifest generate|diff # Artifact manifest generation and diff (--exit-code for CI)
fsp doctor # Environment diagnostics (--test validates built-in templates)
fsp cache status|clean # Cache health check and cleanup
Detailed option listing: CLI Reference.
⚙️ Configuration
Use the [tool.fspack] section in pyproject.toml for icons, exclusion rules,
wheel slimming, private package sources, build defaults, and extras groups.
Multi-entry declaration follows standard PEP 621 [project.scripts]:
[tool.fspack]
icon = "assets/app.ico"
slim-exclude = ["PySide6/translations/*"] # Force-strip during wheel slimming
[project.scripts]
gui = "myapp.gui:main" # Produces gui.exe (no console window)
Full configuration reference: Configuration Guide.
🖥️ Platform Support
| Platform | Runtime | Installer |
|---|---|---|
| Windows | Portable Python (official embed) | NSIS .exe |
| Linux | python-build-standalone | .deb + .tar.gz |
| macOS | python-build-standalone | .pkg + .dmg |
Windows target: Cross-compile from any build machine (Linux/macOS with mingw-w64 →
fsp b --target windows). macOS/Linux targets require same-platform build machines
(cross-machine requests will fail explicitly; --dry-run preview works from anywhere).
Win7 SP1 support: fspack automatically injects API shim DLLs or replaces with
Win7-recompiled python3XX.dll, and outputs a full compatibility scan report.
Supports Python 3.9–3.14. See Distribution Guide.
🔧 CI/CD Integration
fspack itself packages and publishes to GitHub Release with platform-native
runners when a v*.*.* tag is pushed (see
release.yml). For your own projects, follow
that workflow to set up packaging verification and release pipelines — full
guide: CI/CD Integration.
📂 Output Layout
dist/
├── <name>.exe # Executable (double-click to run)
├── runtime/ # Python runtime (portable, no installation needed)
│ └── Lib/site-packages/ # Third-party deps (slimmed + pre-compiled)
├── src/ # Your source code
└── release/ # Installers produced by `fsp p`
├── <name>-setup.exe # Windows installer
├── <name>_<ver>_amd64.deb # Linux .deb
└── <name>-<ver>-linux.tar.gz # Linux portable package
🔐 Security & Distribution
Windows executables automatically embed PE resource sections (VS_VERSIONINFO / manifest / icon) to reduce antivirus false positives. Production distribution recommendations including code signing: Distribution Guide.
🛠️ Development
uv sync --extra dev # Install dev dependencies
uv run pytest -m "not slow" --cov=fspack --cov-fail-under=95 # Tests
uv run pyrefly check # Type check
uv run ruff check src tests # Lint
Run make help for all shortcuts. Architecture and module index:
Architecture Docs.
📚 Documentation
- CLI Reference — All commands and options
- Configuration Guide —
[tool.fspack]options - Offline Packaging — Air-gapped / intranet CI solutions
- Distribution Guide — Secure distribution and Win7 compatibility
- Architecture — Build pipeline, module index, implementation details
- CI/CD Integration — GitHub Actions setup
- API Reference — Auto-generated API docs
- Changelog — Version history
🤝 Contributing
Contributions welcome! Please read CONTRIBUTING.md for guidelines.
📝 License
MIT
Metadata
Release files for fspack 0.6.14
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fspack-0.6.14.tar.gz | 1.3 MB | Without provenance | Details for fspack-0.6.14.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fspack-0.6.14-py3-none-any.whl | Python 3 | none | any | Details for fspack-0.6.14-py3-none-any.whl |
Total release size: 2.1 MB
Release files / fspack-0.6.14.tar.gz
| Download URL | fspack-0.6.14.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7a508359e2208b870ea3755905730f9b6afaab298ec18d3aff055ca4f407577f
|
|
BLAKE2b-256 checksum How to use checksums |
d13c4660d5f6dcc2708fa88bc72a643da05213875505b6ad713723eadde0ea72
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / fspack-0.6.14-py3-none-any.whl
| Download URL | fspack-0.6.14-py3-none-any.whl |
|---|---|
| Size | 820.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dbd3d8cff094c2e3e1fba5ab7e49d0438b3a85ab46e51389383740677c15c2d1
|
|
BLAKE2b-256 checksum How to use checksums |
7ee29243b25351d6b7b55beed259a45a5249ed323a5d7e503ab2862fef9fdd3f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for fspack 0.6.14
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.