Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

wasmhost

WebAssembly from CPython, PyPy and Pythonista, with the JavaScript WebAssembly API: modules, instances, memory, globals, and host functions (Python callables the module calls). It runs on whichever backend is available: JavaScriptCore's JSContext in Pythonista on iOS, JavaScriptCore, Node or Bun on a computer, or, when installed, wasmtime or wasm3 (eight backends in all, see Backends). Plain Python, no C extension of its own; its one dependency, fusedwasi, is pure Python too (it is the WASI host, for WASI 0.1 and for WASI 0.2 over one state; for wasi:http it imports h11, pure Python, which comes with it). It has: Module, Instance, Memory (several per module), Table, Global and Function; limits for untrusted code (max_memory, timeout, fuel, isolated); async and threads; WASI 0.1 (Preview1) and WASI 0.2 (Preview2: one component, or several fused by meld through import_map=; the network denied by default, -S flags, wasi:http; one State shared with Preview1); the commands wasmhost run, self test and bench; examples (CPython for WASI 0.1 and 0.2, git, coreutils, clang, a shell).

license pypi py-versions Made in Ukraine

powered by webassembly

coverage Tests Pre-commit

import wasmhost

module = wasmhost.Module(open("lib.wasm", "rb").read())  # WebAssembly.Module
instance = wasmhost.Instance(module)  # WebAssembly.Instance
print(instance.exports.add(2, 3))  # i32/i64 -> int, f32/f64 -> float
instance.exports.memory.write(ptr, b"data")  # WebAssembly.Memory
print(instance.exports.counter.value)  # WebAssembly.Global

A module that imports functions gets them from the import object, a dict of dicts of Python callables, as in the JavaScript API:

def log(x):  # env.log(i32), which the module calls
    print("the module says", x)


instance = wasmhost.Instance(module, {"env": {"log": log}})
instance.exports.run()  # runs the module, which calls log

See Host functions below, examples/basic.py and examples/imports.py, and for something bigger, both in a bare JavaScript engine:

  • examples/pyodide.py: a Python REPL that runs in Pyodide (CPython built to WebAssembly), with a memory snapshot per backend, fetch served by Python and packages kept between sessions. It started as a gist for a Pythonista JSContext.
  • examples/jslinux.py: a Linux virtual machine (JSLinux, riscv64 or x86_64 Alpine), with its console on your terminal.

examples/cpython/ runs the official CPython (3.15, built to wasm32-wasip1 with wasi-sdk, not Pyodide) on wasmhost.wasi.preview1: python.wasm and its standard library are committed, build.sh makes them from python/cpython, and run.py runs them (python examples/cpython/run.py -c "print(1)"). No processes, sockets or dlopen there, as WASI preview1 has none. python examples/cpython/run2.py -c "print(1)" runs the same CPython built for wasm32-wasip2 (python2.wasm, 8 MB, committed; build_wasip2.sh is meant to rebuild it, written from the recipe that made it but not yet re-run) on Preview2, the one core module of the component that CPython's own build makes. Its exit code is only 0 or 1 (sys.exit(3) gives 1: the export wasi:cli/run#run returns ok or err). Not Pyodide. The network is open by default in run2.py (-S inherit-network=n,allow-ip-name-lookup=n closes it), so sockets work: run by hand on wasmtime, pip install of a pure-Python wheel from a folder and from a plain-http index of a local http.server (pip itself is not in the standard library zip: its wheel goes on PYTHONPATH, --env HOME=...; --env NAME=VALUE sets a variable; a -S flag after the two defaults wins). pip install needs --no-cache-dir: with the cache pip 26.3 stops with AttributeError: module 'mmap' has no attribute 'ACCESS_READ' (the mmap of this build is the stub of sitecustomize). python2.wasm has no ssl (_ssl is not built), so no https; examples/cpython/build_wasip2_ssl.sh builds python2_ssl.wasm with OpenSSL 3.5.0 (11 MB, not committed; run2.py --module python2_ssl.wasm), and with it, by hand on wasmtime and Node (not in CI), get-pip.py and pip install --no-cache-dir --cert ... over https to a local server worked; the guest's own sockets also reached the internet from the build sandbox, but there the TLS ends at the sandbox's egress gateway (its own CA signs the certificate), so that run says nothing about the certificates of PyPI. WASI has no default CA store: give cafile or --cert. Not verified: stdin, another CPython commit, bun/jsc/jscontext/pyodide for the program itself. Every start of run.py and run2.py prints WARN: Could not find the platform standard library directory! on stderr: CPython looks for lib/python3.15/lib-dynload under its home, and the standard library here is the one zip (lib/python315.zip), with no dynamic extensions (WASI has no dlopen). The programs run the same with it; an empty lib/python3.15/lib-dynload folder makes it go away (tried once by hand, not kept).

Both keep their downloads in $WASMHOST_CACHE, else ~/.cache/wasmhost, else ./.cache where there is no usable home directory (PythonIDE).

examples/wasmclang.py compiles C and C++ to WebAssembly with clang and lld that are themselves WebAssembly (the wasm-clang project), with Python as their WASI host, and runs the result, with no compiler installed and no process started, so it works in Pythonista.

examples/coreutils.py is a small shell over uutils coreutils (Rust, built to WASI, in examples/wasm/): ls, cat, sort, cp, seq, wc and the rest, and lua, with pipes and redirects, over a directory of the real file system. The WASI host for the modules is wasmhost.wasi.preview1 (see WASI); the example only gives it a directory and a limit on what a pipe may carry. wasmclang.py takes the calls that are not about files from wasi.preview1 and leaves the file calls to memfs.wasm, a file system that is itself a WebAssembly module; wasi_sh.py keeps a host of its own (a file system in a Python dict, pipes and hooks), because wasi.preview1 is the specification's calls over real folders and nothing more.

examples/wasi_sh.py is a real POSIX shell, BusyBox ash with about fifty utilities (the wasi-sh project's busybox.wasm, downloaded once from npm), with pipes, $(...), here-documents and functions, over a file system that is a Python dict: nothing real is touched. It is made for Pythonista (input() at the prompt, no terminal needed).

examples/git/ is a whole git client for Pythonista (StaSh's git clone, commit, merge, push, ...): git itself and libgit2 built to WASI with zig cc, with Python as their WASI host; libgit2 does the network (http and https), served by the host through four imports, because WASI preview1 has no sockets (WASI 0.2 has them, but these modules are preview1). See examples/git/README.md.

examples/coremark.py runs CoreMark (the wasm3 project's build, in examples/wasm/) on every backend that starts here, to compare their speed. A runtime that finishes the last pass in under 10 s is not scored by CoreMark itself, so it prints the pass time too.

examples/jitcheck.py is a quick check of whether the backend has a JIT: it times a tight wasm loop (50 million additions) on the active backend and prints the speed in millions of iterations per second, then "JIT likely" above 300 and "interpreter likely (no JIT)" below it. It is for a device, where JavaScriptCore may run without JIT (as on iOS without the permission): python examples/jitcheck.py. The threshold is a rough one, not a measurement of the JIT itself; on wasmtime here it printed 2398 M iter/s, "JIT likely".

  • Types. The JavaScript API can't tell a function's signature, and it matters (an i64 argument must reach JavaScript as a BigInt), so the binary's type, import, function, global and export sections are read in Python. Module.exports(module) and Module.imports(module) describe a module with them, and Module.customSections(module, name) gives the contents of its custom sections (a list of bytes).
  • Errors are the API's: CompileError, LinkError and Trap (WebAssembly.RuntimeError, which is also a RuntimeError); an out-of-bounds memory access is an IndexError.
  • Memory is copied, not shared: memory.read(offset, n), memory.write(offset, data), memory[a:b], memory.grow(pages).

Installation

uv

uv add wasmhost

# With wasmtime, the in-process JIT (otherwise Node, Bun or WebKitGTK JavaScriptCore is used)
uv add wasmhost[wasmtime]

pip

pip install wasmhost

# With wasmtime, the in-process JIT (otherwise Node, Bun or WebKitGTK JavaScriptCore is used)
pip install wasmhost[wasmtime]

The wasm3 backend has no extra: pywasm3's PyPI release is years behind the API used here, so install it from git (CPython 3.11+, needs a C compiler): pip install "pywasm3 @ git+https://github.com/wasm3/pywasm3".

Pyodide

The ordinary wheel (pure Python, py3-none-any) installs with micropip, and the pyodide backend is the only one that starts there, so nothing is configured (see Pyodide as a backend for what it can and can not do).

From the Pyodide REPL, or any Python that runs in Pyodide:

import micropip

await micropip.install("wasmhost")

import wasmhost

print(wasmhost.get_backend().name)  # pyodide
wasmhost.selftest()  # the same self-test as anywhere else

From JavaScript, in a browser or in Node (npm install pyodide):

import { loadPyodide } from "pyodide";

const py = await loadPyodide();
await py.loadPackage("micropip");
await py.runPythonAsync(`
import micropip
await micropip.install("wasmhost")

import wasmhost
print(wasmhost.get_backend().name)  # pyodide
wasmhost.selftest()
`);

A wheel built from a checkout (uv build --wheel) installs from its path or URL, e.g. await micropip.install("emfs:/wheels/wasmhost-...-py3-none-any.whl"), after putting the file in Pyodide's file system (py.FS.writeFile, or mountNodeFS on Node). In the repository itself, node tests/pyodide_run.mjs selftest and pytest run the self-test and the suite inside Pyodide.

Pythonista and PythonIDE (iOS)

The ordinary wheel: it is pure Python (py3-none-any). In StaSh (Pythonista) or PythonIDE's pip, pip install wasmhost, then run the self-test (see Try it on a device).

iSH and iSH-AOK (iOS)

iSH is a Linux shell for iOS (an emulated Linux with ordinary CPython); iSH-AOK is a fork of it. Neither has objc_util, JavaScriptCore or Node, so without an engine the self-test ends with no backend could start and says what to install.

  • iSH-AOK (Linux 5.10.0-ish_aok, aarch64): wasmtime installs there and works, and so does wasm3 (WASMHOST_BACKEND=wasm3), both 34/34.

    uv tool install wasmhost --with wasmtime
    wasmhost self test
    
  • The original iSH (Linux 4.20.69-ish, i686): the owner ran it with wasm3 only. It passes 31 of 34 steps; the three that fail all come from one thing, see "On the original iSH, wasm3 starts a memory at its maximum" in Backends.

Both were run by the owner, not by the assistant: see Where it has been run.

Host functions

Instance(module, imports) takes the import object for the module's function imports (Module.imports(module) lists them with their types). A callable gets its arguments as int (i32, i64) and float (f32, f64) and returns what the signature says: None, one value, or a tuple for several results. What it returns is checked (an int for an integer result, a number for a float one) and a wrong answer is a TypeError.

  • An exception raised in a host function comes out of the call into the module that led to it, as the same exception, and the instance is still usable. That holds on every backend.
  • A host function can call the module again (instance.exports.f(...) from inside it), and its own errors come out of the outer call.
  • Errors in the import object are the API's: a missing module is a TypeError, a missing or non-callable function a LinkError. A global, a memory and a table go into the same import object (see below). A backend that can't take host functions says so (backend.supports("imports")), and one that can't take the others says so with import.global, import.memory and import.table.

How a host function is called depends on the backend: wasmtime and wasm3 call the Python function themselves; the JavaScript engines that are JavaScriptCore (jsc, and jscontext on iOS) do it through its C API, which makes a JavaScript function that calls Python; Node and Bun write a request on their pipe and waits for the answer, reading its stdin synchronously. Only gi-jsc can't: PyGObject has no way to make a JavaScript function that calls Python.

Globals

Global(type, value, mutable=False) makes a WebAssembly.Global on its own (or, as in JavaScript, Global({"value": "i32", "mutable": True}, 7)), and an instance can import it, one instance or several:

counter = wasmhost.Global("i32", 0, mutable=True)
a = wasmhost.Instance(module, {"env": {"counter": counter}})
b = wasmhost.Instance(module, {"env": {"counter": counter}})  # the same global: what one writes, the other reads
counter.value = 10  # and so does the host

An exported global (instance.exports.g) can be passed to another instance the same way, and for an immutable one a plain number is enough ({"env": {"limit": 100}}), as in the JavaScript API. A wrong import (a number for a mutable global, another type, another backend) is a LinkError; an immutable global's value can't be written (TypeError). backend.supports("import.global") says whether a backend can (wasm3 can't: pywasm3 makes no global outside a module). A global has to be as mutable as the module says (LinkError otherwise), as in JavaScript.

Memories and tables

Memory(initial, maximum=None) (in 64 KiB pages) and Table("funcref", initial, maximum=None) make a WebAssembly.Memory and WebAssembly.Table on their own, to import into one instance or several (an Emscripten build imports its memory). As in JavaScript they also take a descriptor, Memory({"initial": 1, "maximum": 16}) and Table({"element": "anyfunc", "initial": 2}):

mem = wasmhost.Memory(1, 16)
a = wasmhost.Instance(module, {"env": {"memory": mem}})
mem.write(0, b"shared with every instance that imports it")

table = wasmhost.Table("funcref", 2)
user = wasmhost.Instance(module, {"env": {"table": table}})
table.set(0, provider.exports.add)  # a Function (or None to empty the entry)
table.get(0) is provider.exports.add  # True: one function is one object, as in JavaScript
table.get(0).type()  # FuncType((i32, i32), (i32,)); wasmtime finds it, a JavaScript engine does not tell:
# there a function an `elem` segment put in the table is known, any other: a `ValueError` and `table.get(0).signature = FuncType((i32, i32), (i32,))` (a call looks for it, too);
# a wrong signature given by hand is a `TypeError` when called (the engine checks the type), never a wrong result
table.grow(2)  # the length before
wasmhost.Table(
    "funcref", 2, 4, provider.exports.add
)  # every entry starts as `add`; table.grow(1, f) adds entries of `f`

An import that is not the right object, is too small for the module or comes from another backend is a LinkError.

A module with several memories (multi-memory) needs nothing new: each memory it exports or imports is its own Memory, found by its export name (instance.exports["memory$1"]) or the one the import object gave, and max_memory holds every memory the module defines. A memory that is neither exported nor imported is reachable only through the module's own functions. wasm3 can't import a memory (it can't make one) and the JavaScriptCore engines refuse such a module with a CompileError; see SUPPORTS.md. Only funcref tables are supported (no externref). wasm3 has neither (pywasm3 imports functions only: NotImplementedError).

Like the JavaScript API, all the instances of a backend live in one store, so nothing stops two of them from sharing what the host made. isolated=True is not in the JavaScript API: Instance(module, isolated=True) gives an instance a store of its own, which goes away with it. It matters on wasmtime, which never frees an instance's memory inside a store (only when the store is dropped): the default is one store per backend, freed by wasmhost.close(), so many instances add up (300 instances of 1 MiB were 315 MB, not given back by store.gc()), while an isolated one is freed when the instance is. Its price: it shares nothing (a Global made outside it is a ValueError). backend.supports("isolated") is true for wasmtime and wasm3 (a wasm3 instance is isolated anyway); on the JavaScript engines, which have one store, it is a NotImplementedError.

Types

type() is the type reflection of the JavaScript API, with its names, on a function, a memory, a table and a global (on every backend: the types are read from the module's binary, not asked of the engine, which may not have them):

instance.exports.add.type()  # FuncType(parameters=('i32', 'i32'), results=('i32',))
instance.exports.memory.type()  # MemoryType(minimum=1, maximum=4, shared=False)
instance.exports.table.type()  # TableType(element='funcref', minimum=2, maximum=None)
instance.exports.counter.type()  # GlobalType(value='i32', mutable=True)

Module.imports() and Module.exports() give the same types in the type of each entry, so what a module asks for (the limits of an imported memory or table, whether a global is mutable) can be read before it is instantiated. What type() gives goes back into the constructor: Memory(memory.type()).

Value types are wasmhost.i32, i64, f32 and f64. They are strs (i32 == "i32"), so a name does wherever one of them goes: FuncType((i32, i32), (i32,)) and FuncType(("i32", "i32"), ("i32",)) are the same. An i64 is an int here, as every integer type is; it is what JavaScript takes as a BigInt.

minimum is the size now, as the specification has it (a table's minimum in JavaScriptCore is too; its memory's stays the initial size). A shared memory is refused (NotImplementedError): there are no threads here.

Async and threads

await wasmhost.compile(bytes) and await wasmhost.instantiate(bytes | module, imports) are the JavaScript API's promises (instantiate of bytes gives Instantiated(module, instance), of a Module just the Instance). The synchronous Module(...), Instance(...) and instantiate_sync(...) stay. By default the work is done in place with a turn of the event loop before and after it, and uses no threads, so it works where Python's threads do not. threaded=True does it in a worker thread on wasmtime, node and bun, which keeps the loop free during a long compile (the JavaScriptCore backends and wasm3 are tied to their thread and always run in place).

A backend takes one call at a time: every call into it holds a lock of the backend's own (reentrant, so a host function may call back into the same backend), and two backends never wait for each other. Several tasks or threads may use one backend, one after the other; to run two engines side by side make two backends (wasmhost.NodeBackend() twice), the default one is shared. A host function must not wait for another thread that wants the same backend.

Batches

On a JavaScript engine every call into it has a fixed cost (a pipe to node, a bridged Objective-C call in Pythonista). A batch does several steps in one trip (on wasmtime and wasm3, in Python), and a step can use the results of the earlier ones:

batch = instance.batch()
ptr = batch.call(instance.exports.alloc, len(data))  # a Ref
batch.write(instance.exports.memory, ptr, data)
status = batch.call(instance.exports.run, ptr)
batch.stop_if_nonzero(status)  # leave the rest out on an error status
out = batch.read(instance.exports.memory, ptr, 16)
batch.run()
out.value  # bytes (`.done` says whether the step ran)

A function with several results gives a tuple of Refs (low, high = batch.call(split, x)), each usable by later steps. A failing step (a trap, an out-of-bounds access) raises from run(), after the earlier steps' results are set. Only i32 results can be used in arithmetic (ptr * 8, ptr + 4).

Bytes in and out of a JavaScript engine

A program with JavaScript of its own (Pyodide, an emulator) needs to hand the engine files and read results back. JSBackend.put_bytes(target, data) assigns a Uint8Array to a JavaScript expression (__files["a"]), and JSBackend.get_bytes(expr) returns the bytes of one. On the JavaScriptCore backends (jsc, and jscontext under objc_util) through its C API (ctypes), which fills the array in place; through hex on the others and as the fallback if the C API ever fails. The self-test reports which was used (N bytes via C API or via hex).

Big buffers on Node and Bun

Memory.read and Memory.write of 16 KiB or more do not go over the pipe to node or bun (base64 in a JSON line, about 50 MB/s) but through a file: Python writes it, Node reads it straight into the memory of the module, or the other way round, and only a short line crosses the pipe. The file is in a private directory (mode 0700, /dev/shm where there is one, else the temporary directory) that goes with the backend, and a script in the engine can reach that one file only. About 1.5 to 2.5 GB/s from a 1 MiB buffer (wasmhost bench --buffer 1024), against 50 to 100 MB/s before; below 16 KiB the pipe is as quick. If the directory cannot be made the pipe carries everything, as before. Batches (Batch.read / Batch.write) and put_bytes / get_bytes still use the pipe. wasmtime is faster still, and is first in the order.

Backends

Backend Where How it is detected
wasmtime anywhere with the wasmtime package import wasmtime (pip install wasmtime)
node anywhere with Node.js node on PATH
bun anywhere with Bun bun on PATH. It is JavaScriptCore (as in Safari and on iOS) in a runtime of its own, and runs the very script node does
jsc Linux, macOS JavaScriptCore's C API through ctypes, no PyGObject: apt install libjavascriptcoregtk-4.1-0 (macOS uses the system framework)
gi-jsc Linux the same engine through PyGObject (apt install gir1.2-javascriptcoregtk-4.1 python3-gi, or pip install wasmhost[gi-jsc]: see below)
wasm3 CPython 3.11+ with pywasm3 import wasm3; install it from git: uv add "pywasm3 @ git+https://github.com/wasm3/pywasm3" (its PyPI release predates the API used here)
jscontext iOS (Pythonista, PythonIDE), and a Mac with rubicon-objc Apple's JSContext through an Objective-C bridge: Pythonista's objc_util (both iOS apps have it), or rubicon-objc (pip install rubicon-objc; tested in CI on macOS, not on a device). backend.bridge says which
pyodide inside Pyodide (CPython in WebAssembly: a browser or Node) import js; it calls the WebAssembly of the engine around Python directly (no pip install: Pyodide is not on PyPI, see Pyodide)

With nothing configured, the first backend that starts wins, in the order shown, which is by speed (a JIT before an interpreter), then by how much of WebAssembly the runtime runs, then by what it costs to run: wasmtime, node, bun, jsc, gi-jsc, then the interpreters wasm3 and jscontext, and pyodide last. (On Pythonista nothing above jscontext can be installed, so it is the pick there.) Each backend's constructor is its own probe: it fails when its runtime is missing. Choose one with WASMHOST_BACKEND=<name> (or --runtime <name>, the same as --backend <name>, in run, bench and self test; the option wins over the variable), wasmhost.set_backend("<name>") or Module(..., backend="<name>"); wasmhost.get_backend().name says which is in use. wasmhost.close() closes the backends it started. (In WebAssembly's words the host is the embedder, the Python side that provides imports; what runs the module is the backend.)

Not every backend can do everything; backend.supports(...) says (the same, with the WebAssembly features and the operating systems, as CI measured it: SUPPORTS.md):

memory.grow from Python table.length host functions (imports) Global, Memory, Table on their own (import.*) table get/set/grow (table.funcs) isolated timeout fuel
wasmtime yes yes yes yes yes yes yes yes
wasm3 no (NotImplementedError; a module's own memory.grow works) no yes no no yes (always) yes (an instance that timed out is finished) yes (a trap, the instance goes on)
jscontext yes yes yes, through JavaScriptCore's C API (under either bridge) yes yes no no no
jsc yes yes yes yes yes no no no
gi-jsc yes yes no yes yes no no no
node yes yes yes yes yes no yes no
bun yes yes yes yes yes no no (its wasm loop is not stopped) no

wasm3 has room for 128 live instances in a process. Its guarded memory hands out slots of one arena, a module loaded takes one and a runtime freed gives it back, so the 129th instance alive at once is RuntimeError: memory allocation failed (measured, and the same whether the module has a memory or not). An Instance is in a reference cycle (it holds its exports, which hold it), so one is freed only when Python's cyclic collector gets to it: in a loop that makes many of them, on a build whose collector runs rarely (the free-threaded 3.14t did, in CI), call gc.collect() now and then, or keep them few. The other backends have no such limit.

On the original iSH, wasm3 starts a memory at its maximum. On the original iSH (i686, CPython 3.11.12) a module whose memory is declared as 1 page, at most 4, is 4 pages long from the start: len(memory) is 262144, type() says minimum=4, and the module's own memory.grow(1) answers -1 (it is already at its maximum). The same module has 1 page on 64-bit (Linux x86-64, and wasm3 on iSH-AOK, aarch64: 34/34 there). Three steps of the self-test fail for this reason (module's own memory.grow, Instance(max_memory=) and type() of a memory); the other 31 pass. That is what was observed. The cause is not known and has not been looked into: the owner suspects iSH's emulation of i386 rather than 32-bit as such. Tried to reproduce it on 2026-10-08 and could not: wasm3 as pywasm3 pins it (21f029a, with pywasm3's own compile flags) built as 32-bit x86 against glibc and against musl 1.2.5 (the C library of the iSH wheels), on a real x86-64 kernel, loads a 1..4 page memory as 1 page and coremark-minimal.wasm (2 pages, no maximum, data up to 67 657 bytes) as 2 pages. So neither 32 bits nor musl is the cause; what is left is iSH's emulator, or the wasm3 inside the owner's wheel (0.9.1.dev76+g7562b12f, the pin is dev75). It is the only platform so far where not every test passes.

PyGObject for gi-jsc. The simplest way is the system's own python3-gi (with gir1.2-javascriptcoregtk-4.1) and the system's Python, as CI does. To have it in a venv instead, pip install "wasmhost[gi-jsc]" (or uv sync --extra gi-jsc) builds PyGObject from source, so the system needs its development files first, and which ones depends on the PyGObject that gets built: 3.52 and later need girepository-2.0 (GLib 2.80+: Ubuntu 24.04 and later), 3.50 and earlier need girepository-1.0:

# Ubuntu 24.04 and later (PyGObject 3.52+, the default)
sudo apt install libgirepository-2.0-dev gir1.2-javascriptcoregtk-4.1 libcairo2-dev pkg-config python3-dev build-essential

# an older Ubuntu (22.04): the older development package, and keep PyGObject below 3.52
sudo apt install libgirepository1.0-dev gir1.2-javascriptcoregtk-4.1 libcairo2-dev pkg-config python3-dev build-essential
pip install "wasmhost[gi-jsc]" "pygobject<3.52"

The build stops with Dependency 'girepository-2.0' is required but not found when only the older package is there (seen on Ubuntu 26.04, where libgirepository1.0-dev alone was not enough for PyGObject 3.58). The backend asks for the 4.1 typelib of JavaScriptCore, so on a system that only has 4.0 it does not start: use jsc, which needs no PyGObject. The Ubuntu 22.04 line was not tried here.

No JIT on iOS. In Pythonista (and any app that is not Safari) JavaScriptCore runs WebAssembly without its JIT, so jscontext there is an interpreter: python -m wasmhost bench shows a loop several times slower than jsc on a desktop and close to jsc --no-jit. For plain computation an interpreter such as wasm3 would be faster there, but wasm3 is a C extension that can not be installed on iOS; the cost of a call from Python is the same either way (the bridge dominates).

Deno is not supported. Run on its pipe protocol like Node, it passes all of the self-test but the exception-handling step: Deno (2.9.6 and 2.9.7 tried) panics ("Deno has panicked", capacity overflow) when a WebAssembly.Exception leaves vm.runInContext, which is what a module that throws an exception of a tag the caller does not catch does there. Node and Bun are the same V8 and JavaScriptCore without this. It is an upstream bug; see BACKLOG.md (B-701b).

Pyodide as a backend

wasmhost can also run inside Pyodide, and then the backend is the WebAssembly object of the JavaScript engine that Pyodide runs in, called through Pyodide's js module, with no source text evaluated and no process started. Load the package into Pyodide (micropip.install a wheel, or mount the source) and it is picked by itself, as nothing else can start there:

import wasmhost  # in Pyodide

instance = wasmhost.Instance(wasmhost.Module(data))  # backend: pyodide

It takes host functions and globals, memories and tables made on their own and imported. It has no timeout, fuel or isolated (supports(...) says so; Python has one thread there and nothing to stop a call with), and no Memory.view (Pyodide copies a buffer when it makes a memoryview). Threads do not exist in Python on Emscripten, and the tests that need them, symbolic links or the per-thread CPU clock are skipped there.

The self-test and the whole suite run in CI inside Pyodide on Node (tests/pyodide_run.mjs); to try it here:

npm install --global pyodide            # or `npm install pyodide` in the folder you run from
node tests/pyodide_run.mjs selftest     # python -m wasmhost self test --backend pyodide, inside Pyodide
node tests/pyodide_run.mjs pytest       # the suite on the pyodide backend (needs a network for pytest's wheel)

--backend pyodide on an ordinary Python only says "No module named 'js'", as expected.

What has run where

yes means it has run: on the assistant's computer, in CI, or by the owner on a device. no means it fails. n/a means it cannot: wasmtime and wasm3 are not JavaScript engines, so the Pyodide example, which is JavaScript glue, does not apply to them, and gi-jsc takes no host functions, so nothing that imports anything runs on it. ? is not run or not looked at.

Program wasmtime wasm3 node bun jsc jscontext gi-jsc pyodide
the WASI programs of the self-test (both snapshots) yes yes yes yes yes (CI) yes (CI, device) n/a yes (CI)
coreutils.py (uutils coreutils in Rust, and Lua) yes yes yes yes yes (CI) yes (CI, device) n/a ?
wasi_sh.py (BusyBox ash) yes yes yes yes yes (CI) yes (CI, device) n/a ?
wasmclang.py (clang and lld, themselves wasm) yes (21 s) yes (14 s) yes no: Bun aborts ? yes (device, 22 s) n/a ?
pyodide.py n/a n/a yes yes ? yes (CI, device, ready in 1.9 s) n/a n/a
coremark.py (score) 25405 3645 30411 29731 ? 1951 (iPhone 16), 1892 (PythonIDE) n/a ?
jslinux.py ? ? ? ? ? yes (device) n/a ?
git/git.py (git and libgit2, over http/https) yes yes yes partly: Bun crashes on checkout ? ? (not run on a device) n/a ?

The first four CoreMark scores are from one x86-64 computer and the jscontext one from a phone without JIT, so they say an order of magnitude and not more. wasmclang.py on Bun stops with panic: abort() called and Bun's own "this indicates a bug in Bun" (Bun 1.4.2, in the second build, the WASI program); the file as it was before 2026-10-07 does the same. Pyodide's own pyodide.asm.wasm does not link on wasm3 in any case: it imports 280 globals, which our wasm3 backend can't give, and uses externref. jslinux.py needs a server that the assistant's environment cannot reach.

Known problem: PyPy on macOS with the jsc backend. On PyPy 3.11 (macOS, arm64) the jsc backend, the system JavaScriptCore through ctypes, sometimes ends the process with a segmentation fault in JSValueToStringCopy. It happens when Python reads the memory of a module from inside a host function that the module itself called (for example fd_write of a WASI program, as in coreutils.py), so a run of the test suite hits it about once in ten to twenty-five repeats, with the JIT of JavaScriptCore on or off. It was not seen on CPython on macOS, on PyPy on Linux (WebKitGTK's JavaScriptCore, 30 repeats), or with any other backend. The cause is not known; on macOS use CPython for jsc, or another backend (wasmtime, node, bun) on PyPy. Details are in BACKLOG.md.

CoreMark built natively (C, -O2, not through wasmhost), as a baseline for the devices where iSH emulates the processor: 3169 (GCC 15.2.0, 60000 iterations, 18.9 s, "Correct operation validated") on iSH-AOK 1.3 (557), Linux 5.10.0-ish_aok aarch64; 1590 (GCC 12.2.1, 20000 iterations, 12.6 s, also validated) on the original iSH, Linux 4.20.69-ish i686. Through wasmhost (examples/coremark.py, the wasm3 project's build of CoreMark) on iSH-AOK: wasmtime 2571.2 (the last pass 15.6 s) and wasm3 207.2 (14.5 s; a pywasm3 wheel built for musllinux aarch64), that is about 81 % and 6.5 % of the native 3169. The last pass is calibrated by each runtime to take over 10 s, so its time says nothing about speed: the scores do. On the original iSH (i686) wasm3 does not get as far as a score: examples/coremark.py stops with failed: data segment out of bounds (the owner's run, 2026-10-08; the same platform as the 3 failed memory steps of the self-test, cause not investigated). These numbers are not comparable with the table's above either (another machine, another build of the benchmark).

Limits for untrusted code

Three limits, each an extension outside the JavaScript API except the first road of the memory ceiling. What an engine can't do is a NotImplementedError (backend.supports("timeout"), supports("fuel")), never a silent no-op.

Backend Memory ceiling timeout fuel
wasmtime yes yes yes
wasm3 yes yes yes
node yes yes no
bun yes no no
jsc, gi-jsc, jscontext yes no no

So on iOS (jscontext) only the memory ceiling exists: do not run untrusted code there expecting a time limit.

Memory. memory.grow past the ceiling answers -1 and nothing else changes. A module that imports its memory (Emscripten IMPORTED_MEMORY, wasm-ld --import-memory) is held as in JavaScript: give it Memory(initial, maximum) (not on wasm3, which has no imported memory). A memory the module makes itself, with no maximum, is held by Instance(module, max_memory=pages) (also in instantiate and instantiate_sync): the maximum is written into a copy of the module, so it works the same on every engine, and the copy for a given ceiling is compiled once and kept.

Time. Instance(module, timeout=seconds) ends a call that runs longer with a Timeout (a Trap). It is wall-clock time, per call (a batch is one call; the start function and host functions are under it too).

  • wasmtime: by epochs. The instance gets an engine that counts them, a tight loop runs about 3 times slower, and it lives in a store of its own, so it can't share a Memory, Table or Global made outside it. The instance can be called again.
  • node: vm's timeout. A Timeout in a batch drops the results of the steps before it. The instance can be called again.
  • wasm3: no thread can stop a call (it holds the GIL), so the call is cut into slices of gas (about 5 ms of a tight loop, about 8% cost) and the clock is looked at between them, using pywasm3's suspendable runs. A paused call can't be cancelled, so an instance that timed out is finished: every later call is a Trap that says so (other instances, and a new one from the same module, are fine).
  • bun (its vm timeout leaves a wasm loop running) and the JavaScriptCore ones (a script's time limit does not reach a wasm loop, checked with JSContextGroupSetExecutionTimeLimit): not possible.

Fuel. Instance(module, fuel=n) ends a call that uses more than n units with an OutOfFuel (a Trap). It is deterministic, the same on every machine, and needs no thread. The unit is the engine's own (a turn of a tight loop is 8 on wasmtime, under 0.1 on wasm3), so a number does not carry from one engine to the other. Each call starts with the whole budget (a batch is one call; a call from a host function shares the outer one).

  • wasmtime: consume_fuel. The instance gets an engine that counts fuel (a tight loop about 2.4 times slower) and a store of its own, like a timed one.
  • wasm3: pywasm3's gas. A clean trap, and the instance goes on; with a timeout too it can't (the call is in slices), as after a Timeout.
  • Node, Bun and the JavaScriptCore engines have nothing to count with.

timeout and fuel can be given together; whichever runs out first ends the call (on wasmtime that instance pays for both engines, about 5 times slower on a tight loop).

WASI

wasmhost.wasi.preview1 is a host for wasi_snapshot_preview1 (WASI 0.1), the interface that Rust (wasm32-wasip1), wasi-sdk, Zig and most "command line" modules are built against: all 46 functions of the specification, in plain Python. The calls themselves are those of the package fusedwasi (a dependency of wasmhost: pure Python, py3-none-any, nothing else to install; one fusedwasi.State (one class for WASI 0.1 and 0.2) is the world of a Preview1 and one Guest is each instance), the Python twin of the C core that wasmext builds into its modules; the two are tested against each other with the same scripts of calls. wasmhost.wasi.preview1 gives them the shape wasmhost has: the options below, the import objects of the engines, and the tables of the specification. It also offers wasi_unstable, the first snapshot, which older toolchains (wasienv, wasm-clang) still produce and which the Lua build of examples/coreutils.py imports from. It is checked against the specification's own witx files of both snapshots (names, signatures, the numbers of errors and flags, the layout of the records), and its self-test step runs a small WASI program of each on every backend.

It runs on the pyodide backend too (wasmhost inside Pyodide; the self-test step and the tests pass there; with fusedwasi as the host the self-test passes, and the whole suite is the CI job "Pyodide"), with what Emscripten lacks: the files a program sees are Pyodide's virtual file system (on Node a real folder can be mounted with mountNodeFS), there are no symbolic links (path_symlink and path_readlink fail). Python there has no per-thread CPU clock, so thread_cputime_id reads the process's CPU clock, which is the same thing with one thread.

import sys
from wasmhost import Module
from wasmhost.wasi.preview1 import Preview1

wasi = Preview1(
    args=["prog", "-v"],
    env={"HOME": "/"},
    preopens={"/": "some/folder"},
    stdin=b"input",
    stdout=sys.stdout.buffer.write,
)
code = wasi.run(Module(open("prog.wasm", "rb").read()))  # the exit code: what `proc_exit` was given, else 0
  • Names. wasmhost.wasi is a package with a module for each version of WASI: preview1 is WASI 0.1, with the class Preview1, and preview2 is WASI 0.2, with Preview2 (see WASI 0.2); the package exports both classes (from wasmhost.wasi import Preview1, Preview2). A class has the version in its name, so one cannot be taken for the other.
  • Folders. preopens maps the name the program sees to a folder of the host; several can be given, and a name that leaves its folder (.., an absolute name, a link that points out) is refused with ENOTCAPABLE. On POSIX a name is walked from the folder one step at a time with openat, and a link met on the way is read and its target put in front of the rest of the name (a name that passes through a folder that is not there is ENOENT, not ENOTCAPABLE: it is walked as it comes). The files are fusedwasi's, and so are the limits of this; what its authors report (2026-11-05, their S0015, a draft at fusedwasi 0.1.0b3 with options A to F: what a preopen promises, a regression test, openat2, and for Windows a walk by handle; we did not repeat it): on POSIX a folder holds against a change of the tree under the walk, because the kernel is given one name at a time relative to a directory it already holds, with no link followed by the kernel; a stress run (Linux, the Python twin, 8 s: 82,602 opens while the tree was changed 126,670 times) found no escape. That is one run, not a proof, and the C twin was read, not run. A folder shared with another process: a guest can plant a link that leads out (WASI 0.2 symlink-at refuses only an absolute target; WASI 0.1 path_symlink refuses a link that leaves), which the walk never follows but another process that reads the same folder will, so treat the links in a shared folder as untrusted. On Windows a preopen is not a barrier against another process that can change the folder: there is no openat, a name is resolved by hand and checked against the real paths, and the check and the open are two steps (a junction can be made without a privilege); a walk by handle (NtCreateFile with a RootDirectory) is not built. Nothing here was run on Windows or macOS.
  • Read-only. readonly=True makes every preopen read-only, readonly={"data"} only the ones of those names. The rights that change something are taken away from the folder (and so from what is opened in it), so a call that would write, make, remove, rename or link answers ENOTCAPABLE, and a file opened with every right asked for is opened for reading only.
  • Streams. stdin is bytes or an object with read(n) (default: empty, there is no interactive input); stdout and stderr are callables that take bytes, or objects with write (default: the interpreter's own streams).
  • Running. wasi.run(module) instantiates, starts and closes. To give options to the instance, or to make it yourself, use wasi.instantiate(module, timeout=5) and wasi.start(instance), or wasi.imports() with wasi.bind(instance): the import object has both snapshots, and the engine links the one a module asks for. Each imports() is the calls of one more instance over the same world (the same files, arguments, environment and standard streams, and a memory of its own: bind(instance) gives it the memory of the instance whose import object came from the last imports(), and instantiate does the pairing by itself), so several instances can run over one Preview1. fusedwasi reads and writes the memory of the instance through a view where the engine gives one (wasmtime, wasm3) and otherwise through read/write of the range a call touches.
  • wasi_unstable is the same calls with four differences (the order of whence, one right less, a 32-bit link count in filestat, and a clock subscription with an extra field) and no sock_accept.
  • Errors. A read of standard output and a write to standard input are EBADF; a name that is not UTF-8 is ENOENT on POSIX (a name is bytes there) and EINVAL on Windows; unlinking a directory is EISDIR on Linux and EPERM on macOS (what the system says); a seek by 0 bytes from the current position needs only the right to tell. These are the answers of fusedwasi, and so of wasmext.
  • Not supported: sockets (ENOTSOCK), signals (ENOSYS: proc_raise does not end the program here, whereas in wasmext it does; wasmhost gives fusedwasi a signal hook that answers ENOSYS, since without one fusedwasi answers ENOTSUP; signal 0, "none", is success (0) and a number above 30 EINVAL, both answered by fusedwasi itself). A host function that sleeps (poll_oneoff) is outside what timeout and fuel can stop.

WASI 0.2

wasmhost.wasi.Preview2 runs the core module of one WASI 0.2 component: what wasm-tools component unbundle leaves (one memory exported as memory, an export cabi_realloc, the export wasi:cli/run@0.2.N#run, flat wasi:*@0.2.N imports), on every backend that takes host functions. Its imports are answered by fusedwasi over a State; a real component is refused by Module as before, and a module of WASI 0.3 is not supported (a wasi: import fusedwasi has no function for is a LinkError). A module that meld fused from several components runs with import_map= (below).

from wasmhost import Module
from wasmhost.wasi import Preview1, Preview2

code = Preview2(env={"A": "1"}, stdout=out.append).run(
    Module(open("prog.wasm", "rb").read())
)  # 0 ok, 1 err, or the code of wasi:cli/exit
shared = Preview2(state=Preview1(preopens={"/": "dir"}).state)  # the same files, arguments, environment and streams
  • Options. The same as Preview1 (args, env, preopens, stdin, stdout, stderr, readonly), run(module), or instantiate(module) and start(instance); bind(instance, memories=("memory",), reallocs=("cabi_realloc",)) takes other export names.

  • Network: denied by default. network=True opens sockets; socket_addr_check=lambda ip, port, use: ... decides each bind or connect (a check that says no is the default's denial); allow_ip_name_lookup is fusedwasi's. http=True opens wasi:http (a switch of its own: it needs no network=True), http_check(scheme, authority) decides each request and http_send(request) -> response replaces the transport (without it fusedwasi's own client sends the request, on h11; run against a local http.server in tests/test_wasi_http.py, plain http only, the guest reads the status: CI green on ab99e81; https and the guest reading the body were not run); fusedwasi still calls wasi:http unstable in its alpha (0.1.0b3), so its behaviour may change. A blocking socket call holds the backend (one call at a time).

  • One call for both. wasmhost.wasi.for_module(wasm, **options) reads the imports of the bytes and gives a Preview1 (WASI 0.1, or no WASI import) or a Preview2 (WASI 0.2); a component, WASI 0.3, bytes that are no module, or an option only Preview2 has (network, http, import_map...) for a 0.1 module is a ValueError. wasmhost run uses it. host.imports(module) works on both.

    wasm = open("prog.wasm", "rb").read()
    with for_module(wasm, args=["prog"], stdout=out.append) as wasi:
        code = wasi.run(Module(wasm))
    
  • Shared state. Preview1 and Preview2 have a state, and either takes state= (then no other option is given). Whoever made a State closes it.

  • Run one from the command line (every command below was run again on 2026-11-05, second pass, with the default backend, wasmtime; the first also on node; the modules are in tests/data/wasi2/):

    wasmhost run tests/data/wasi2/one.wasm                    # a core module of one component: prints "hello from wasip2", exit 0
    wasmhost run -S inherit-network,tcp=n tests/data/wasi2/_sock.wasm   # a TCP client, TCP refused again: "connect: Permission denied", exit 1 (`examples/wasi2.py sock --network` runs it against a server)
    # a module fused from two components by meld (here two_multi.wasm, two memories): the map says which memory each wasi:* import uses,
    # and this module exports no wasi:cli/run, so --invoke names the export
    wasmhost run -S http tests/data/wasi2/http.wasm            # asks 127.0.0.1:47124 for GET /x?q=1 and writes the status if it gets one (the test server answers 200); with nothing listening it prints nothing and exits 0
    wasmhost run --import-map tests/data/wasi2/two_multi.map.json --invoke 'demo:m/app@0.1.0#run' tests/data/wasi2/two_multi.wasm   # prints three lines, then 42
    

    In Python the same is Preview2(import_map="two_multi.map.json").instantiate(Module(data)) and a call of the export (run: inst.exports["demo:m/app@0.1.0#run"]() gave 42). meld and wasm-tools themselves were not run for this section (the files are the ones the tests carry; the commands that made them are in docs/experiments/s0004_meld/). The exit code of wasi:cli/run#run is only ok or err, so a program that calls exit(3) gives 1 (shown with CPython, examples/cpython/run2.py); wasi:cli/exit gives its own code.

  • How to run a component, step by step (unbundle, meld fuse, the errors): docs/COMPONENTS.md.

  • Try it: python examples/wasi2.py hello (a WASI 0.2 program says hello), python examples/wasi2.py sock (a TCP client: the network is denied) and python examples/wasi2.py sock --network (it connects to a local server); see examples/wasi2/README.md.

  • Several components, fused by meld (S0004). meld fuse a.wasm b.wasm --memory multi --emit-import-map fused.map.json -o fused.wasm (meld 0.65 or later; the map is schema version: 2, any other version is a ValueError) leaves a memory and a cabi_realloc* for each component. Preview2(import_map="fused.map.json") (a path, or the loaded JSON) sends each wasi:* import to the memory and cabi_realloc of its own component (the $N suffix of a name is stripped to find the function); the other imports (your interfaces, resource intrinsics) are yours: {**wasi.imports(module), **mine}. wasmhost run --import-map fused.map.json --invoke NAME fused.wasm does the same. A module with several cabi_realloc* exports and no map is a ValueError (the routing is not guessable); a wasi:* import that the map lacks or could not trace ({"unknown": ...}), or that the module lists twice, is a LinkError naming it. A module with ONE cabi_realloc is run as one component and a map is ignored: this includes meld --memory shared --address-rebase, where every component's calls reach the one cabi_realloc; that is safe only with an allocator that does not free another component's block, and meld itself calls the mode unsound (it refuses memory.grow under rebasing, so a component with wasi-libc's malloc, as CPython has, can not be fused that way). Several memories do not run on JavaScriptCore (jsc, gi-jsc, jscontext). Test modules and the commands that made them: tests/data/wasi2/README.md, docs/experiments/s0004_meld/.

Try it on a device

The package carries a self-test, since nothing else can be run in Pythonista/Python IDE to see whether this works there:

import wasmhost

wasmhost.selftest()  # or, from a shell: python -m wasmhost self test [--backend NAME] [--all]

It prints one line per check, then N/M passed: the Objective-C bridge in use (and, if the C API is not used, why: C API not used: ...), WebAssembly and BigInt in the engine, bytes in and out (via C API or via hex), calls, i64, memory, globals, traps, batches, host functions, a WASI program, globals made on their own and shared between instances, an isolated instance, which encodings of WebAssembly exceptions the engine takes (final (try_table): yes, older (try/catch): no: a module built with C++ exceptions, such as bclibc's bclibc_wasm.wasm from wasi-sdk, needs the final one), and the cost of a call. A check the backend can't do says so (not available on this backend, as documented) and counts as passed. If something fails, send the whole output. On a computer, python -m wasmhost self test --all runs it on every backend that starts. Installed with pip, the same commands are there as wasmhost self test and wasmhost bench.

wasmhost run [OPTIONS] module.wasm [-- ARGUMENTS] runs a module along the lines of wasmtime run (the results, the exit codes and the options were compared with wasmtime 48.0.5; --invoke with too many words is an error here, and the -W/-O/... groups are not there). A module with _start is a WASI command (wasmhost.wasi.Preview1) and its exit code is the command's; --invoke FUNCTION calls an exported function instead, the words after the module being its arguments (wasmhost run --invoke add m.wasm 2 3 prints 5; one result per line, a float as Rust prints it: 0.5, NaN, inf). Options: --backend, --dir HOST[::GUEST] (repeatable), --readonly, --env NAME[=VALUE], --inherit-env (all the variables of the process; --env wins), --argv0 NAME (the default is the module's file name), --max-memory PAGES, --timeout SECONDS, --fuel UNITS, and for WASI 0.2 only -S/--wasi KEY[=VALUE][,KEY...] and --import-map PATH. --runtime NAME is --backend NAME. A trap exits with 134, as in wasmtime; any other error with 1. Everything after the module belongs to the program. Only the WASI functions are provided: a module that imports others (examples/coremark.py's env.clock_ms) does not link, as in wasmtime; programs like that are run from Python, as the examples do.

A core module of WASI 0.2 (imports wasi:*@0.2.N, as wasm-tools component unbundle leaves it for one component) is told from one of 0.1 by its imports and runs on Preview2: it calls wasi:cli/run#run, and --invoke works as above. --import-map PATH is the map of meld fuse --emit-import-map for a module fused from several components. The network is denied; Wasmtime's -S flags open it: -S inherit-network (all addresses, TCP and UDP; the name lookup stays off), -S allow-ip-name-lookup, -S tcp=n and -S udp=n (refuse that kind again; tcp alone changes nothing), several in one -S with commas. -S http (or http=n) opens wasi:http outgoing requests on its own, with no socket flag; without it a request is refused (HTTP-request-denied). Three errors, each exit 1: a component (make a core module of it with wasm-tools component unbundle or meld fuse), a module of WASI 0.3 ("WASI 0.3 is not supported"), and -S or --import-map on a module that is not of WASI 0.2.

python -m wasmhost bench [--backend NAME] [--no-jit] [--buffer KIB] times a call, a batch of three, moving a buffer in and out of memory (MB/s) and the engine itself (a recursive fib, a loop) on each backend that starts, to choose one. --no-jit takes the JIT off JavaScriptCore (JSC_useJIT=false): where there is none, an interpreter such as wasm3 can be several times faster.

Where it has been run

Where Backend Result A call / a batch of 3
Pythonista 3 (StaSh 0.7.5), Python 3.10.4, iPhone 16 (iPhone17,3) jscontext (objc_util) 25/25, bytes via C API, host functions (wasmhost 0.0.2b1) 55 / 102 us
Pythonista 3, Python 3.10.4, iPhone 16 (iPhone17,3), iOS 26 (Darwin 25.6) jscontext (objc_util) 28/28, bytes via C API, host functions, both encodings of WebAssembly exceptions (try_table and try/catch) (wasmhost 0.0.3b2) 40 / 85 us
Pythonista 3, Python 3.10.4, iPhone 16 (iPhone17,3), iOS 26 (Darwin 25.6) jscontext (objc_util) 35/35, bytes via C API, both encodings of exceptions, functions and signatures, async, threads (wasmhost 0.0.4.dev64) 68 / 156 us
Pythonista 3, Python 3.10.4, iPhone 16 (iPhone17,3), iOS 26 (Darwin 25.6) jscontext (objc_util) 36/36, a 1 MiB buffer moves at 5400 MB/s in and 12700 MB/s out (a typed array through the C API; through hex it was about 40) (wasmhost 0.0.4.dev84) 36 / 84 us
Pythonista 3, Python 3.10.4, iPhone 16 (iPhone17,3), iOS 26 (Darwin 25.6) jscontext (objc_util) 38/38, a memory held by the maximum of an imported Memory and by Instance(max_memory=) (wasmhost 0.1.0b2.dev3) 36 / 83 us
Pythonista 3, Python 3.10.4, iPhone 16 (iPhone17,3), iOS 26 (Darwin 25.6) jscontext (objc_util) 41/41, wasmhost.wasi.preview1: a WASI program of each snapshot (wasi_snapshot_preview1 and wasi_unstable) with arguments, stdout, a file and an exit code; timeout and fuel "not available", as documented (wasmhost 0.1.0b3.dev14) 47 / 111 us
Pythonista 3, Python 3.10.4, iPhone 16 (iPhone17,3), iOS 26 (Darwin 25.6) jscontext (objc_util) 41/41 after the rename to wasmhost.wasi.preview1 (the wheel 0.1.0b3.dev20+gb9498e8f6; the output does not print the version), and the examples coreutils, coremark, imports, basic, jitcheck, jslinux, pyodide, wasi_sh and wasmclang run 37 / 94 us
PythonIDE, Python 3.14.7, ios-13.0-arm64-iphoneos jscontext (objc_util) 25/25, bytes via C API, host functions (wasmhost 0.0.2b1) 39 / 77 us
PythonIDE, Python 3.14.7, ios-13.0-arm64-iphoneos jscontext (objc_util) 41/41, the same, WASI step included (wasmhost 0.1.0b3.dev14) 44 / 102 us
iSH-AOK 1.3 (557), a fork of iSH, Linux 5.10.0-ish_aok aarch64, CPython 3.14.8 wasmtime 34/34 (wasmhost 0.1.0b2, uv tool install wasmhost --prerelease=allow --with wasmtime; without wasmtime no backend starts there and the self-test says so) 1615 / 5500 us
iSH-AOK 1.3 (557), Linux 5.10.0-ish_aok aarch64, CPython 3.14.8 wasm3 (WASMHOST_BACKEND=wasm3) 34/34, wasmhost 0.1.0b2 (the memory steps pass: the 64-bit wasm3 starts a memory at its initial size) 213 / 1191 us
iSH (the original), Linux 4.20.69-ish i686, CPython 3.11.12 wasm3 31/34, failed: the module's own memory.grow, Instance(max_memory=), type() of a memory (wasm3 starts a memory at its maximum there, see Backends); wasmhost 0.1.0b2 571 / 3157 us
Linux, CPython 3.14t jsc 35/35 32 / 102 us
Linux, CPython 3.14t gi-jsc 27/27 (host functions: not available, as documented) 35 / 62 us
Ubuntu 26.04, CPython 3.10.20, PyGObject 3.58.0 (pip, built from source) gi-jsc 38/38 (host functions: not available, as documented) 32 / 74 us
Linux, CPython 3.14t node 35/35 82 / 340 us
Linux, CPython 3.11, Bun 1.4.2 bun 35/35 133 / 287 us
Linux, CPython 3.14t wasmtime 29/29 66 / 212 us
Linux, CPython 3.14t wasm3 29/29 3 / 63 us
Linux, CPython 3.10 and PyPy 3.10 node 25/25 (an earlier version; and the test suite on 3.10)

Each count is that of the version the row was run on, and the self-test has grown since the older rows (it has 35 steps on wasmtime and wasm3 now, and 41 on the JavaScript engines); the times are one run of the self-test each, so read them as an order of magnitude. A host function costs about what a call does, plus a round trip on node or bun (measured once: about 4 us on wasm3, 50 us on wasmtime and jsc, 200 us on node, per host call including the export around it).

Host functions and the C API bytes path on jscontext have run on both iOS apps above; on Linux they also run against a fake objc_util whose c is the real JavaScriptCore library, and on macOS in CI against a real Objective-C JSContext through rubicon-objc. Not run on a device: the rubicon-objc bridge (both iOS apps have objc_util, so it isn't needed there). Node's synchronous wait for a host function's answer has run in CI on Linux, macOS and Windows; Bun's, in CI on Linux and macOS (not on Windows yet).

A note on wasmtime and faulthandler

wasmtime installs process-wide signal handlers when its first engine is created, and uses them to catch a trap. Python's faulthandler (on with python -X faulthandler, and in pytest) replaces the handlers when it is enabled after that, and the first trap then ends the process (Fatal Python error: Illegal instruction). Enable it first (or not at all), or start the backend later: this repo's tests/conftest.py does that.

Not yet

What the JavaScript API has, or a module can need, and wasmhost does not have yet. ROADMAP.md says what waits for what; BACKLOG.md has the order in which it is meant to be done. SUPPORTS.md says what each backend supports today, measured by CI.

  • Tables and references. The signature of a table entry is not told by a JavaScript engine (set it by hand, or let the module's elem segment tell it; wasmtime finds it); no externref (tables, globals or values); no v128.
  • Memory is copied on read and write. Memory.view(offset, length) gives the engine's own memory as a memoryview, with no copy, on wasmtime and wasm3 (not on a JavaScript engine, whose memory lives in another place); it is released when the module may have run (a call, a batch, a grow), so it is for use at once. On a JavaScript engine the cost of moving a buffer is in the encoding, not the copy: see wasmhost bench.
  • Limits on untrusted code are only partly possible: a memory ceiling everywhere, a timeout and a fuel count only where the engine can do it, and none of the last two on iOS. See "Limits for untrusted code" above.
  • Threads. A module built with -pthread (the WebAssembly threads proposal: a shared memory that the module imports, atomic instructions, threads made by the host as several instances of the module on one memory) does not run: Memory(..., shared=True) raises NotImplementedError, so it can not be given as an import. Build without threads (-pthread off, for wasm-ld --no-threads). A wasm instance runs in one thread, and a backend takes one call at a time (a lock of its own, see "Async and threads").
  • Newer proposals: no API for WebAssembly.Tag and WebAssembly.Exception (the self-test only reports which encodings of exceptions an engine takes), SIMD, memory64, multi-memory, GC types. Whether a module that uses them runs is up to the engine: SUPPORTS.md has a probe of each feature on every backend, from CI. (GC types are not added to wasmhost yet, whatever the engine can do: B-604.)
  • WASI is provided for wasi_snapshot_preview1 by wasmhost.wasi.preview1 and, for a core module of one WASI 0.2 component or of several fused by meld, by wasmhost.wasi.Preview2 (see WASI, sockets included, denied by default); not yet: a safe open on Windows (there is no openat: the check of a name and the open are two steps there; on POSIX a name is walked with openat, see WASI). examples/coreutils.py uses it and examples/wasmclang.py uses it for the calls that are not about files; wasi_sh.py keeps a host of its own (a file system that is not a folder, pipes).

Test

uv run pytest                            # every backend that starts here
uv run pytest --wasm-backend node        # one backend: it must start, or the run stops with an error
uv run pytest --wasm-backend bun         # needs `bun` on PATH
uv run pytest --wasm-backend wasmtime    # or wasm3, or jsc (needs the JavaScriptCore library)
uv run pytest --wasm-backend gi-jsc      # needs PyGObject: `uv sync --extra gi-jsc` after the packages above, or a system-site-packages venv (the CI job)
uv run pyright && uv run ruff check
node tests/pyodide_run.mjs pytest        # the suite inside Pyodide (see [Pyodide as a backend](#pyodide-as-a-backend))

Metadata

Release files for wasmhost 0.2.0b1

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

Source distribution (sdist)

Source distribution for wasmhost 0.2.0b1
File Size Uploaded Provenance Actions
wasmhost-0.2.0b1.tar.gz 16.1 MB With provenance Details for wasmhost-0.2.0b1.tar.gz

Built distribution (wheel)

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

Total release size: 16.2 MB

Release files / wasmhost-0.2.0b1.tar.gz

Download URL wasmhost-0.2.0b1.tar.gz
Size 16.1 MB
Tags Source
SHA-256 checksum
How to use checksums
584101f53f7128a902d433350d49d50e0b703f4c764b3bedacac0572e446fe73
BLAKE2b-256 checksum
How to use checksums
fca1453f3de4c93eeaecef0235e155d21ec9802db082a3ee92eca2ef3a3ceea3
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 6, 2026.

Transparency log

Release files / wasmhost-0.2.0b1-py3-none-any.whl

Download URL wasmhost-0.2.0b1-py3-none-any.whl
Size 123.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0fdb3650f826dd2c8c51b0b841fb3a0acc26ee3b5f86d763573f3c6e6b3c6423
BLAKE2b-256 checksum
How to use checksums
04de3d96876b7d8d2957b504e4af0ce12a22c7b3de5a4adba6c859fdcfdd5922
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 6, 2026.

Transparency log

Security for wasmhost 0.2.0b1

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 wasmhost-0.2.0b1.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 6, 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.

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