Skip to content

Build & Distribution

Ship your TauPy application as a ready-to-run package.

1. Quick path: one command

taupy build

What happens: 1. Frontend - runs npm run build if package.json is present (skipped otherwise). 2. Backend - bundles main.py with Nuitka (onefile by default). 3. Launcher - copies taupy.exe and WebView2Loader.dll. 4. Packaging - writes everything into ./target/.

Resulting layout:

target/
  app.exe              # bundled backend
  dist/                # static assets (React/Vite output, client.js)
  launcher/
    taupy.exe
    WebView2Loader.dll

2. Prerequisites

Tool Why Notes
Python 3.9+ Backend build Same version as dev recommended
Nuitka Bundle backend pip install nuitka
Node.js (optional) Build React/Vite Required only if package.json exists
Rust toolchain (optional) Custom launcher Needed only if you rebuild the launcher yourself

Check setup: 

python -m nuitka --version
node -v   # if using React
npm -v    # if using React

3. Configure the build

Settings live in taupy.toml (generated by taupy new). Key sections:

[build]
onefile = true     # bundle backend into a single exe
strip = true       # strip symbols (smaller binaries)

[build.modules]
# extra Python modules Nuitka should include explicitly
numpy = true

Common flags: - onefile: true for a single EXE; set to false for dir mode if AV tools are aggressive. - strip: remove debug symbols to shrink output. - [build.modules]: list modules that Nuitka might miss during import detection.

Frontend-related: - If package.json exists, taupy build runs npm run build. - To skip frontend build, temporarily move or rename package.json (or delete it in CI after building yourself).

4. Dev vs production serving

  • Dev (taupy dev): usually uses TAUPY_EXTERNAL_HTTP=1 so the launcher loads Vite on 5173; WebSocket defaults to 8765.
  • Build/Prod (taupy build): AppMode.RAW_HTML serves dist/ via the launcher's tiny HTTP server. Keep external_http = false in taupy.toml so assets load locally.
  • Override ports via env vars: TAUPY_HTTP_PORT, TAUPY_WS_PORT. In production you normally do not set TAUPY_EXTERNAL_HTTP.

5. Step-by-step release workflow

1) Clean and install deps 

pip install -U -r requirements.txt      # or poetry install
pip install nuitka
npm install                             # if React/Vite

2) Build frontend (optional) 

npm run build
This writes assets into dist/.

3) Build TauPy bundle 

taupy build
Find output in target/.

4) Test the packaged app 

cd target
./app.exe   # or double-click in Explorer

5) Distribute - Zip the target/ folder, or - Wrap it with an installer (MSI, Inno Setup, NSIS), or - Copy app.exe, dist/, and launcher/ into your deployment pipeline.

6. What is inside the bundle

  • launcher/taupy.exe: Rust + WebView2 host that opens the desktop window.
  • launcher/WebView2Loader.dll: loader for the WebView2 runtime.
  • dist/: static assets for raw HTML or React builds (includes client.js for Python widgets).
  • app.exe: Nuitka-compiled backend (contains Python, your code, and dependencies).

7. Customizing the launcher

Default builds reuse the prebuilt launcher. If you need to patch it: 

cd taupy/window
cargo build --release
Then replace launcher/taupy.exe in your project (and keep WebView2Loader.dll).

8. Code-signing and AV friendliness

  • Onefile vs dir mode: If antivirus tools flag app.exe, set onefile = false to produce a directory build.
  • Signing: Sign app.exe and launcher/taupy.exe with your code-signing certificate after taupy build.
  • WebView2: End users need the WebView2 runtime (most Windows 11 systems have it; installer link: https://go.microsoft.com/fwlink/p/?LinkId=2124703).

9. Troubleshooting

  • nuitka not found: install with pip install nuitka in the active environment.
  • npm run build fails: fix React errors first; ensure Node and npm versions match your package.json engines.
  • Port already in use during build preview: set TAUPY_HTTP_PORT or stop the conflicting process.
  • WebSocket not connecting in packaged app: ensure firewall allows localhost 8765; avoid setting TAUPY_EXTERNAL_HTTP in production.
  • Blank window in prod: check that dist/ exists next to app.exe and launcher/, and that external_http is false.

10. CI tips

  • Cache node_modules and .venv/.cache for faster builds.
  • Run npm run build and taupy build as separate steps; fail fast on lint/type errors.
  • Store target/ as an artifact and run smoke tests launching app.exe headless if possible.