Skip to main content

title: README kind: guide status: current updated: 2026-11-02

waboros

New here? Read BRIEF.md first.

A WebAssembly compiler and runtime for Python with no runtime dependencies: the Python standard library is all it needs. Its core is a compiler written in Python that emits machine code at run time; the public API will take the familiar shape of wasmtime-py (Engine, Store, Module, Linker, Instance, WASI), which is also the test oracle. Where Wasmtime has Cranelift (or Winch, Pulley), waboros has targets: a translator to Python code (pyc), a translator for MicroPython (mpy) and machine-code JITs written in Python that run through mmap + ctypes (jit-x86_64, jit-aarch64, later jit-riscv64, …). A target is picked automatically for the machine (never by a module's content, D25), and its output can be cached.

Status: the package is under development (branch phase0-skeleton; BRIEF.md has the state): pyc and the JITs jit-x86_64 and jit-aarch64 pass the same spec-suite core; SIMD is being added (S0005); the public API is phase 6. Everything under poc/ is the proof of concept: it works on CoreMark (the code passes CoreMark's own self-check on every target) but covers only what CoreMark needs. The documents under docs/ are the plan.

Why

CoreMark, it/s needs
wasmtime (Cranelift) 19 044 a 30+ MB native wheel
PoC jit-x86_64 (w2jit2), CPython 3.8–3.13 15 337–15 437 stdlib only
wasm3 (pywasm3) 2 433 a native extension
PoC pyc (poc/w2py.py), PyPy 7.3 2 300–2 900 stdlib only
PoC mpy, MicroPython 1.29 unix, @native 94 nothing
PoC pyc, CPython 3.13 86–100 stdlib only
pywasm 2.2.3 (pure-Python interpreter) 0.58 stdlib only

Same machine (cloud x86-64, Xeon 2.1 GHz); the first three rows in one session. Full table, conditions and history: docs/BENCHMARKS.md.

So: a JIT where the platform allows executable memory (about 80 % of Wasmtime, 6× wasm3), Python code everywhere else (iOS/Pythonista, hardened systems, unknown architectures), MicroPython where possible.

The documents

docs/ARCHITECTURE.md layers, the IR (HIR/LIR), the Wasmtime object model, the pipeline, cache, stack depth and recursion, long calls and the GIL, traps, memory, WASI
docs/TARGETS.md the target interface, automatic selection, how to add an architecture step by step, the targets planned
docs/ARTIFACT.md the JIT artifact as a language-neutral, versioned contract: ISA levels, the file format, the context ABI
docs/API.md the Python API (after wasmtime-py) and the CLI (after the wasmtime binary)
docs/FEATURES.md what Wasmtime supports, what waboros must support, the state of each target
docs/TESTING.md the spec test suite, differential testing, benchmarks, CI matrix
docs/BENCHMARKS.md every measurement made, with conditions
docs/RISKS.md risks with possible solutions (not decisions): moving artifacts between machines and trust, version skew between generator and runtime, platforms restricting JIT and CPU control-flow integrity, alternatives to a hand-written JIT
docs/REFERENCES.md projects to read for how things are done correctly (Winch, V8 Liftoff, wasm2c, TinyCC, asmjit, DynASM, MicroPython's emitters, …) — read, understand, write our own
docs/DECISIONS.md the decisions taken and the alternatives rejected, with the reasons
docs/LESSONS.md traps found while building the PoC (bugs, platform limits)
docs/ROADMAP.md the phases of the work and the open questions
CLAUDE.md context and rules for working on this repository with an agent

The proof of concept (poc/)

file what it is
w2py.py wasm → Python translator (CPython, PyPy, --micropython, --legacy, --mypyc, --inline N)
w2jit.py JIT for x86-64 System V, every value in memory: 3 874 it/s
w2jit2.py the same JIT with pinned locals, a top-of-stack register and fused updates: 15 337 it/s
w2lua.py, w2luajit.py the same translator for Lua 5.4 and LuaJIT (an experiment: 271 / 1 873 it/s)
run_*.py, ref_run.py runners: CPython, PyPy, MicroPython, mypyc, Lua, the JITs, and the references (wasmtime, wasm3, pywasm)
bench/ micro-benchmarks behind the decisions (memory access, ctypes call cost, MicroPython viper, …)
in/core.wasm CoreMark built with zig cc -O3 for wasm32; imports wiring.millis and wiring.print, exports setup
out/, mypyc/ what the translators produced for it
patches/warpy-coremark.patch what warpy (an RPython wasm interpreter) needed to run CoreMark
cd poc
python3 run_jit2.py in/core.wasm            # the JIT, any CPython >= 3.8 on x86-64 Linux
python3 w2py.py in/core.wasm out/core.py    # translate; then:
python3 run_pyc.py out/core.pyc             # CPython
pypy3   run_py.py  out/core.py              # PyPy

poc/README.md lists every mode and flag of the PoC.

Metadata

Release files for waboros 0.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for waboros 0.0.0
File Size Uploaded Provenance Actions
waboros-0.0.0.tar.gz 699.2 kB With provenance Details for waboros-0.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 840.2 kB

Release files / waboros-0.0.0.tar.gz

Download URL waboros-0.0.0.tar.gz
Size 699.2 kB
Tags Source
SHA-256 checksum
How to use checksums
dbcfbc2a421f9641c1040b7eac2a2fab93cd4544d29f9faccd5fda09460fecb4
BLAKE2b-256 checksum
How to use checksums
231089b081b4c65e4b112167aaca0bfa38ca4ad39debea73dcc3ee89dc114f90
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Release files / waboros-0.0.0-py3-none-any.whl

Download URL waboros-0.0.0-py3-none-any.whl
Size 141.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b7d7149334735698b98957b5f71832a0cf4168a76223b9e68829bfa4e9c12e0b
BLAKE2b-256 checksum
How to use checksums
5e56b8d2ce965e6cd2a10123aa16a37af3dddd20b18512b658cb201a4ccd789f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Security for waboros 0.0.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for waboros-0.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

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.0.0 This release

2 release files Full 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