Skip to main content

fspack

One-command Python packaging — produce executables and installers.

PyPI CI Python License Coverage Release Downloads

English | 简体中文

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 b builds, fsp p packages — cargo-style two-letter shortcuts
  • Zero config: AST-based import analysis 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=1 for air-gapped CI/packaging machines
  • Monorepo-friendly: fsp b -R recursively builds all sub-projects
  • Nuitka boost: --nuitka flag 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

fspack workflow demo

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

🤝 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)

Source distribution for fspack 0.6.14
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)

Table of built distributions (wheels) for fspack 0.6.14
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.6.14 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page