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).
Want to make your own? See scripts/record_demo.py.
🚀 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) |
fsp init |
fsp i |
Scaffold new project from templates (18 available) |
fsp doctor |
— | Environment diagnostics — check toolchain availability |
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|all>] [-R]
fsp init [name] [--template <id>] [--list]
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
Two GitHub Actions workflow templates provided:
pack-check.yml— PR validation buildrelease-pack.yml— Release packaging
Copy to .github/workflows/, set PROJECT_NAME / EXPECTED_OUTPUT variables, done.
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.8
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.8.tar.gz | 1.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| fspack-0.6.8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.8 MB
Release files / fspack-0.6.8.tar.gz
| Download URL | fspack-0.6.8.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f8a49af3187387d66068effecf57af47f6a800d24e3d7027549b8b02307521d2
|
|
BLAKE2b-256 checksum How to use checksums |
2e5b4896686e80d4e954755c17411f8ffdd5657e55bcfe85c3fb298cde2ef7d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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.8-py3-none-any.whl
| Download URL | fspack-0.6.8-py3-none-any.whl |
|---|---|
| Size | 713.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55504aaa7130794ade794c0f0354aab65051ccdd004b01d53b42ede442d3c266
|
|
BLAKE2b-256 checksum How to use checksums |
c0d3c3241c8314aa94c1a80e800033a5eb905328c4bbae46b3440f306c36614c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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}
|
