# Running Python in a Tauri app as a supervised sidecar

> Run Python as a child process that the Tauri app watches and restarts. The parts, the order to build them in, and the pitfalls a template already handles.

- Type: essay
- Published: 2026-11-22
- Author: Mats Hoppenbrouwers (hoponthestack)
- Canonical URL: https://www.frameworkreboot.com/writing/python-in-tauri-sidecar

To run Python in a Tauri app, I run it as a [supervised sidecar](/glossary/supervised-sidecar): a separate child process that the Rust side spawns, watches and restarts, rather than an interpreter embedded in the binary. The two processes talk over an authenticated connection on loopback, and for release the Python is compiled into a single executable that the installer carries alongside the app. This piece walks through those parts in the order I would build them, and points at a template where each one exists as working code.

The template is [tauri-python-sidecar](/products/tauri-python-sidecar), currently v0.1.1, MIT licensed, with the source at [github.com/matshoppenbrouwers/tauri-python-sidecar](https://github.com/matshoppenbrouwers/tauri-python-sidecar). It is a Tauri v2 app extracted from CommandLane, a desktop app I discontinued; I wrote about why I published it in [What a discontinued app leaves behind](/writing/what-a-discontinued-app-leaves-behind). The code stays in the repository, with the reasoning attached as comments.

## Sidecar or embedded interpreter

The reason to choose a sidecar is failure isolation. A segfault in a native extension, an out-of-memory kill, or a C library that calls `exit()` takes down a sidecar, and something notices. In an embedded runtime the same failure takes down the whole application, window and all. The second reason is an existing Python codebase: a sidecar takes the code as it is.

Embedding is a real alternative. The template's README describes PyTauri, which embeds Python in the Tauri process through PyO3: one process, no transport, no supervision, direct calls. It calls that the better choice for a lot of applications and suggests looking at it first if you are starting fresh with no constraints. Choose the sidecar when you want a crash in Python to be something the app survives and shows.

## The pieces you need

1. **Spawn and supervise.** A monitor thread restarts the sidecar on unexpected exit along a [backoff ladder](/glossary/backoff-ladder): delays of 1, 2, 5, 5 and 5 seconds, after which it emits `failed` and stops. It is capped because a dead sidecar is either transiently unlucky, where a second or two is enough, or broken in a way waiting will not fix, where the user needs to be told. The attempt counter resets after 300 seconds of health, so an app left open for a week does not spend its five attempts on unrelated crashes. This lives in `src-tauri/src/lib.rs`, with the general case in `src-tauri/src/supervisor.rs`.

2. **Add a local transport and authenticate it.** The template uses TCP on `127.0.0.1` with newline-delimited JSON-RPC: one line in, one line out. A loopback port is reachable by anything running as the same user, so the Python side generates a token at startup and writes it to a file created at mode 0600. The client's first line on each connection carries the token, and the server compares it in constant time with `hmac.compare_digest`. The renderer can call only the methods named in `ALLOWED_METHODS`. The supervisor injects `SIDECAR_DATA_DIR` at spawn so both sides look for the token in the same directory.

3. **Make state survive several processes.** At launch, the sidecar, a worker and a one-shot invocation can all open the same SQLite file within the same second. The migration runner in `sidecar/storage/` checks a sentinel, takes a cross-process file lock, checks again inside the lock, then applies, so each migration runs exactly once. At startup the app checkpoints a write-ahead log left by a hard kill, and gates the recovery on a health check: a successful checkpoint is still followed by a `SELECT 1`.

4. **Clean up after crashes without killing strangers.** The sidecar holds a PID lock file, and the app sweeps stale locks at startup, because a detached sidecar survives a hard kill of the app. Preparing the template surfaced a bug here. The sweep read a process ID from a stale lock file and killed whatever held it, and operating systems reuse process IDs as soon as they are free, so the number could belong to an unrelated program. Now the lock file records the worker's image name next to its PID, and the sweep kills only when the live process still carries that name. A lock file with no recorded name is not killed either.

5. **Package the Python.** `packaging/nuitka-build.py` compiles the sidecar with Nuitka into one executable and renames it to `py-sidecar-x86_64-pc-windows-msvc.exe`, the name the app's `externalBin` entry resolves to. The binary is built with the console disabled, which leaves it with no valid standard streams, so `sidecar/server.py` redirects `stdout` and `stderr` to a log file.

6. **Sign it and hook the installer.** The sidecar executable needs signing, not just the app; `packaging/sign.ps1` does it and exits 0 with a warning when no credentials are configured. The NSIS hooks in `src-tauri/nsis/hooks.nsh` kill children that escaped the process tree, and their `$UpdateMode` guards stop an update from deleting the user's data.

7. **Update in the right order.** The update flow in `ui/src/hooks/useUpdater.ts` takes a backup, aborts the whole update if the backup failed, kills the sidecars, then installs. `packaging/generate_latest_json.py` writes the updater manifest, because a mismatched tag, signature or version produces an update that never arrives, with no error anywhere.

## Pitfalls the template already handles

**Nuitka's import graph.** In CommandLane the build peaked at around 14 GB of RAM because Nuitka followed imports into the machine-learning libraries. Excluding them with `--nofollow-import-to` took it to roughly 2 GB.

**`no_annotations`.** The flag `--python-flag=no_annotations` looks like free size savings. Pydantic v2 reads annotations at runtime, so the binary compiles clean and the models then fail. The template does not use Pydantic, but the warning stays in the build script.

**`--show-progress`.** It crashes the build, as does `--show-memory`. Both are present but commented out in the build script.

**`cargo test` dying on Windows.** In a Tauri project, `cargo test` can die in the loader before a single test runs, with `STATUS_ENTRYPOINT_NOT_FOUND`. The test binary gets no application manifest, so it binds against the old system copy of comctl32, which lacks one exported function. The fix is a cargo runner that patches the manifest into test binaries only when one is missing. The template's own tests do not trigger the failure, so the runner is opt-in, with this command from the README: `cargo test --config .cargo\test-runner.toml`. I also posted the fix as a comment on the Tauri issue, [tauri-apps/tauri#13419](https://github.com/tauri-apps/tauri/issues/13419). That issue was closed on 18 November 2026 by a change to `tauri-build` that links the Windows resource into all targets, so on a Tauri release that includes it the runner should no longer be needed; on anything older it still is.

## Using the template

The README's prerequisites are Windows 10 or 11, the Rust MSVC toolchain, Python 3.10 or later, and Node 18 or later with pnpm. Its development commands, copied from `README.md`:

```powershell
git clone https://github.com/matshoppenbrouwers/tauri-python-sidecar
cd tauri-python-sidecar

py -3 -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dev]"

pnpm install
pnpm dev:app
```

Two details matter. Use the virtual environment's Python explicitly, because a bare `python` may resolve to another installation, and the sidecar then dies at startup until the supervisor has used all five attempts. Use `pnpm dev:app` rather than `pnpm tauri dev`, because it first creates the placeholder sidecar binary that the build script checks for.

The demo window shows a status badge and the sidecar's PID. Run `taskkill /F /PID <the PID shown in the UI>`, watch the status go to `down`, and about a second later it comes back as `restarted` with a different PID. To adapt it, search for `TODO_YOUR_`.

## What it does not cover

The README is exact about platform: "Windows is the platform this was built and verified on. The Rust is cross-platform where the monorepo it came from was; the packaging and the process handling are Windows-specific and say so." I have not verified it anywhere else.

Windows ignores the 0600 mode; the token is protected there by living under the user's own `%APPDATA%`, which does not defend against an administrator. The port allocator has a documented race between releasing the port and the child binding it. The frozen binary pays roughly one to three seconds of cold start, again on every restart.

The transport is about 600 lines you would own, with no OpenAPI schema and no `curl` against a running sidecar; the README says FastAPI over loopback HTTP is a perfectly good choice. The updater ships wired but switched off, and its backup call is a documented stub.

No maintenance is promised. I do not know that anyone will clone it, and a template with no users is just a repository with good comments.
