# Whitebox WASM Engine vs Python Sidecar for Geoprocessing: What's the Difference?

> Compare the Whitebox WASM engine for in-browser geoprocessing with the Python sidecar for heavy workloads. Discover the best approach for your GIS data.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: comparison
- Published: 2026-08-15

---

**The Whitebox WASM engine runs geoprocessing tools directly in the browser via WebAssembly with zero installation required, while the Python sidecar executes tools in a separate FastAPI process using the native `whitebox-workflows` package for larger datasets and heavier workloads.**

GeoLibre, an open-source geospatial processing platform developed by opengeos, provides **two interchangeable back-ends** for running Whitebox geoprocessing tools. Understanding the difference between the **client-side Whitebox WASM engine** and the **Python sidecar** helps you choose the right execution model for your data size, latency requirements, and deployment constraints.

## Where Each Engine Runs

### Client-Side Whitebox WASM Engine

The WASM engine executes **directly in the browser** (or Tauri desktop WebView) as a WebAssembly (WASI) binary. No server infrastructure, no Python interpreter, and no external dependencies are required.

- Implementation resides in [`packages/processing/src/wasm-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/wasm-client.ts) [[source]](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/wasm-client.ts)
- The `geolibre-wasm/tools` bundle contains the `wbtools_oss` engine plus GeoLibre-authored extensions
- Lazy-loaded at approximately 5 MB gzipped
- Executes inside an in-memory WASI filesystem

### Python Sidecar

The sidecar runs in a **separate FastAPI process** (`backend/geolibre_server`) that launches a native Python interpreter to import and execute the `whitebox-workflows` package.

- Core logic in [`backend/geolibre_server/geolibre_server/app/whitebox.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/whitebox.py) [[source]](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/whitebox.py)
- Uses official `whitebox-workflows` package (≥ 2.0.2)
- The `/whitebox/run` endpoint receives a `WhiteboxRunRequest`, spawns a subprocess in a temporary directory, and streams output back

## Memory, Resources, and Performance

| Characteristic | WASM Engine | Python Sidecar |
|----------------|-------------|----------------|
| **Memory ceiling** | ~4 GiB (browser WebAssembly limit) | Host machine RAM only |
| **Threading** | Single-threaded | Multi-core capable |
| **Large datasets** | Must fall back to sidecar | Native handling |
| **Latency** | In-process, no network overhead | HTTP inter-process communication adds latency |
| **Throughput** | Faster for typical vector/raster sizes | Faster for very large inputs with native I/O |

## Installation and Deployment

**WASM engine** offers **zero-install deployment**:
- Shipped with the web application
- No `pip`, `uv`, or native wheels needed
- Works offline once loaded

**Python sidecar** requires environment setup:
- Python with `whitebox-workflows`, `rio-cogeo`, and optional extras
- Runtime managed via `uv` on-demand
- Customizable via `GEOLIBRE_WHITEBOX_PACKAGE` environment variable

## Fault Isolation and Reliability

Both engines provide crash isolation, but differently:

- **WASM crashes**: Browser tab reload recovers without affecting the application
- **Sidecar crashes**: Isolated to the separate FastAPI process; requires HTTP retry logic and adds recovery complexity

## Feature Parity and Algorithm Support

The WASM engine provides **identical algorithms and outputs** as the sidecar. The WASM binary is a compiled superset of Whitebox tools, as noted in [`wasm-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/wasm-client.ts) lines 5-7 [[source]](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/wasm-client.ts#L5-L7).

The sidecar adds **Python ecosystem access**:
- Native third-party raster utilities
- Python-only extensions
- Custom preprocessing or postprocessing scripts

## Code Examples

### Running a Tool with the Client-Side WASM Engine

```typescript
import { runWhiteboxToolWasm } from "@geolibre/processing";

const request = {
  tool_id: "slope",
  parameters: { z_factor: "2" },
};

const job = await runWhiteboxToolWasm(request);
console.log("WASM job finished, output files:", job.output_paths);

```

### Running the Same Tool Through the Python Sidecar

```typescript
import fetch from "node-fetch";

const response = await fetch("http://localhost:8765/whitebox/run", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    tool_id: "slope",
    parameters: { z_factor: "2" },
    include_pro: false,
    tier: "open",
  }),
});
const job = await response.json();
console.log("Sidecar job ID:", job.job_id);

```

## Key Source Files

| Component | Path | Purpose |
|-----------|------|---------|
| WASM runner | [`packages/processing/src/wasm-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/wasm-client.ts) | Core runner and tool-manifest handling |
| Sidecar router | [`backend/geolibre_server/geolibre_server/app/whitebox.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/whitebox.py) | FastAPI endpoints, request models, runtime management |
| Tool catalog | [`apps/geolibre-desktop/public/whitebox-catalog-snapshot.json`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/public/whitebox-catalog-snapshot.json) | Shared tool definitions used by both engines |
| WASM conversion | [`packages/processing/src/wasm-convert.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/wasm-convert.ts) | COG output formatting for browser-side results |
| Sidecar conversion | [`backend/geolibre_server/geolibre_server/app/conversion.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/conversion.py) | COG post-processing for Python-run jobs |

## Summary

- **Choose the WASM engine** for interactive, low-latency processing without installation overhead—ideal for buffers, reprojections, and simple raster operations on moderately sized data
- **Choose the Python sidecar** for batch processing, datasets exceeding 4 GiB, multi-core workloads, or when you need Python ecosystem integrations
- Both engines share the same tool catalog and produce equivalent outputs, enabling seamless fallback from browser-side to server-side execution

## Frequently Asked Questions

### Can I use both engines in the same GeoLibre deployment?

Yes. GeoLibre automatically routes jobs based on data size, tool availability, and user preference. The same `tool_id` and parameters work identically in both the `runWhiteboxToolWasm()` function and the `/whitebox/run` HTTP endpoint.

### What happens if a WASM job runs out of memory?

When a WASM operation approaches or exceeds the ~4 GiB browser limit, GeoLibre can transparently fall back to the Python sidecar if configured. The [`wasm-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/wasm-client.ts) implementation detects large inputs and recommends server-side execution.

### Does the Python sidecar require a permanent server?

No. The sidecar launches on-demand via `uv` and can run locally on a developer machine or as a containerized service. Environment variables control which Python packages and versions are used.

### Are Whitebox Pro tools available in both engines?

Pro tools require authentication and are gated by tier validation. The WASM engine respects the same `tier` and `include_pro` flags as the sidecar, though some Pro features may be restricted in the open-source WASM bundle depending on your license.