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 on Linux, wine on Windows) |
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
1 maintainer
Metadata
1 maintainer
Release files for fspack 0.6.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| fspack-0.6.9.tar.gz | 1.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| fspack-0.6.9-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.9 MB
Release files / fspack-0.6.9.tar.gz
| Download URL | fspack-0.6.9.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
df45504113a1770e6345e0143ed32055b98915a33ba612ec644f916842c70ff3
|
|
BLAKE2b-256 checksum How to use checksums |
1636729f149b4b06cc43dbeb94989d5476089a18df6c29479ba3224a5b780a14
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.22 {"installer":{"name":"uv","version":"0.12.22","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","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.9-py3-none-any.whl
| Download URL | fspack-0.6.9-py3-none-any.whl |
|---|---|
| Size | 747.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c268a65f2ecb8355ca420d40e75ba8659227fc9eb61338de14f86997b8395011
|
|
BLAKE2b-256 checksum How to use checksums |
8f6bc482379a657f4cc3a3aeccab14fecba3235b744de0dbb2e493c165f205d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.22 {"installer":{"name":"uv","version":"0.12.22","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
