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 verify — Verify artifact binary format and target arch (PE/ELF/Mach-O)
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 verify                # Verify artifact binary format and target arch
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 Arch Runtime Python versions Installer
Windows x86_64 Portable Python (official embed) 3.8–3.14 NSIS .exe
Linux x86_64 python-build-standalone 3.10–3.14 .deb + .tar.gz
macOS x86_64 / arm64 python-build-standalone 3.10–3.14 .pkg + .dmg

Version ranges are limited by upstream runtime assets: python-build-standalone no longer publishes 3.8/3.9, so those versions are Windows-only. Free-threaded builds (3.13t/3.14t) are available on all three platforms via standalone tarballs.

One invocation produces one target: platform comes from --target, architecture from the build machine (macOS picks x86_64 or arm64 automatically; Windows/Linux are x86_64 only), and Python version from --py-version. There is no --arch flag yet, and every run writes to the same dist/ directory.

Build & CI status: Windows and Linux are built on native runners in the release workflow. macOS packaging runs in two native cells (e2e-macos job): arm64 on macos-latest and x86_64 on macos-15-intel.

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>-<ver>-py<ver>-windows-x86_64-slim-setup.exe   # Windows installer
    ├── <name>_<ver>-py<ver>-slim_amd64.deb                  # Linux .deb
    └── <name>-<ver>-py<ver>-linux-x86_64-slim.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.15

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.15
File Size Uploaded Provenance Actions
fspack-0.6.15.tar.gz 1.3 MB Without provenance Details for fspack-0.6.15.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fspack 0.6.15
File Interpreter ABI Platform Actions
fspack-0.6.15-py3-none-any.whl Python 3 none any Details for fspack-0.6.15-py3-none-any.whl

Total release size: 2.2 MB

Release files / fspack-0.6.15.tar.gz

Download URL fspack-0.6.15.tar.gz
Size 1.3 MB
Tags Source
SHA-256 checksum
How to use checksums
4186400892745356e464fefbd2069f632964d94977827a4b65a2210429e47b87
BLAKE2b-256 checksum
How to use checksums
e83c5e335483bba099c31311f216d80b3c1d31b4c4b760c6685796acec369aa0
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.15-py3-none-any.whl

Download URL fspack-0.6.15-py3-none-any.whl
Size 836.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e713e85db195045ddf31a9c786c1b45d030b73b1eca6e6a6add30cfb2c0bc69
BLAKE2b-256 checksum
How to use checksums
43ac5a262855d7d984249e7a2a4b67407ed1e81f87881c98bd7f7431a7127ae8
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.15

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.15 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