Waspy compiles typed Python ahead of time into a standalone WebAssembly module, with no interpreter inside. Built in Rust for performance and reliability.
cargo add waspy
Adding waspy v0.18.0 to dependencies
Waspy is a Rust library: add it to your project and compile Python to WebAssembly from your own code, or try it in the browser first.
Compiled ahead of timeNo interpreter or VM in the module you ship.
CPython's answerOr a located compile error, never a silent wrong one.
Standard .wasmRuns in browsers, Node.js, wasmtime, and at the edge.
Pipeline
From Python source to optimized WebAssembly in four steps.
Parsed with RustPython's parser
Lowered to Waspy's own intermediate representation
Emitted with wasm-encoder, then validated
Shrunk by Binaryen, when you ask for it
Write Python, compile it from Rust, run it from JavaScript or TypeScript.
def fibonacci(n: int) -> int:
if n <= 1:
return n
a, b = 0, 1
for i in range(2, n + 1):
a, b = b, a + b
return b
def factorial(n: int) -> int:
result = 1
for i in range(1, n + 1):
result *= i
return resultOrdinary, type-annotated Python is the compiler's input. Annotations pick the WASM value types: int and bool become i32, float becomes f64.
// in your Rust project,
// after `cargo add waspy`
use waspy::compile_python_file;
fn main() -> Result<(), Box<dyn std::error::Error>> {
// parse → typed IR → codegen → Binaryen
let wasm =
compile_python_file("fibonacci.py", true)?;
// a standalone module,
// no Python interpreter inside
std::fs::write("fibonacci.wasm", &wasm)?;
Ok(())
}cargo run turns fibonacci.py into fibonacci.wasm. Every top-level Python function becomes a WASM export, and imports of sibling .py files link in automatically.
// Node 18+
// (TypeScript works the same)
import { readFile } from "node:fs/promises";
const wasm = await readFile("./fibonacci.wasm");
const { instance } =
await WebAssembly.instantiate(wasm);
console.log(instance.exports.fibonacci(10));
// 55
console.log(instance.exports.factorial(5));
// 120node run.mjs prints 55 and 120: your Python, running as WebAssembly. In a browser, swap readFile for fetch and WebAssembly.instantiateStreaming.
let wasm = waspy::compile_python_to_wasm(&source)?;
Compile Python you already hold in memory, no files involved.
let wasm = waspy::compile_python_project("./my_project", true)?;
Compile a project directory into one module, with __main__.py entry detection and pyproject.toml config.
More in the library guide and on docs.rs.
How Waspy compares across performance, safety, and portability.
Features
What the compiler supports today, from parser to binary. The Python subset lists it in full, and per-feature status lives on the modules board.
Python compiles to a WASM binary before it runs, with no interpreter or VM in the output.
no runtime VMType annotations map to WASM value types (i32 for ints and bools, f64 for floats), checked at compile time.
annotationsA construct either gives the answer CPython gives or is refused at compile time with a located error. Nothing unsupported is silently accepted.
correctness firstThe binary can run through Binaryen passes: dead-code elimination, inlining, constant folding. The unoptimized module is already valid and correct.
optimizerEmits plain .wasm modules that load in browsers, Node.js, wasmtime, and edge runtimes. A program with a __main__ block is a WASI command.
.wasmClasses with multiple inheritance, closures, lambdas, generators, comprehensions, exceptions, f-strings, and decorators.
python 3 syntaxcompile_python_to_wasm() for one source, compile_python_file() for an entry file and its imports, compile_python_project() for a directory.
rust crateMulti-file input with import resolution, __main__.py entry detection, and pyproject.toml config, linked into one .wasm. User modules resolve from disk, each compiled once.
one .wasm outModule constants, sys streams, argv and exit, re.sub and re.escape folded over constant arguments, and the functools decorators. Every other stdlib call is refused at compile time.
stdlib subsetUnder the hood
How a project becomes one module. Hover or focus any node to see what happens at that stage.
compile_python_project
The input: a directory of Python modules. compile_python_file starts from a single entry file instead and follows its imports.
core::config::load_project_config
Reads pyproject.toml, setup.py, and __version__.py or __about__.py for the project's name and version, and collects the Python files to compile.
imports resolved, each module once
Every module is gathered once, however many import paths reach it (from an entry file, sibling imports resolve from disk, transitively). The __main__ entry point is looked for in __main__.py first, then in the other files.
parse_python, lower_ast_to_ir
For each file: RustPython's parser turns the source into an AST, which is lowered to a typed IRModule. Module passes then desugar user decorators, metaclasses, nested functions, keyword arguments, with, and generators.
memory_layout.merge_from
The per-file modules merge into one IRModule with one flat namespace: functions, classes, variables, and dispatch tables combine and the memory layouts merge. Two files defining the same function name is a compile error, never a silent pick.
DecoratorRegistry, add_entry_point_to_module
The built-in decorators are applied and a detected __main__ block becomes the entry point, which makes the program a WASI command exporting _start.
compile_ir_module
Lays out classes (their MRO and fields), module globals, and the module init, then generates each function through the compilation context (type tables, function indices, memory layout) with wasm-encoder. Only the runtime helpers and WASI imports the program uses are added.
validated, functions exported
A standalone WebAssembly module, validated before it is returned, with every top-level function exported. It is already correct: nothing depends on the optimizer.
optimize_wasm
When optimization is on, Binaryen applies its passes (dead-code elimination, constant folding, inlining, and more) for a smaller, faster binary.
On stage
Where Waspy has been presented, with recordings and slides where they exist.
Kumar Anirudha, Farhaan Bukhsh
Innovations in Compiler Technology, IISc Bengaluru. How Waspy maps typed Python onto WebAssembly's static types and linear memory with no embedded interpreter, producing modules of a few kilobytes.
Kumar Anirudha, Farhaan Bukhsh
Why Python still lags behind in the browser, what Pyodide, PyScript, and RustPython trade away to get there, and how a native ahead-of-time compiler like Waspy closes the gap.
Kumar Anirudha, Farhaan Bukhsh
EuroPython 2025, Prague. WebAssembly against containers for serverless workloads, what makes Python hard to run in WASM, and a FastAPI function deployed in a WASM runtime and benchmarked against a traditional server.
Spoke about Waspy somewhere? Add your talk to this page.
The people
Waspy is built in the open by everyone who has sent a patch, an issue, or an idea.
Loading contributors from GitHub…
Waspy is free and open source under the MIT license, and it gets better every time someone new pokes at it. A compiler is a big surface: the parser, the IR, codegen, the runtime, the docs you are reading right now. There is room for a first commit at almost any level of experience.
Pick up a good first issue, report a Python snippet that miscompiles, teach the compiler one more builtin, or just tell us what you tried to build and where it broke. Every one of those genuinely moves the project forward, and we would love to work on it together.