wazero

wazero is a WebAssembly runtime written entirely in Go that lets a Go application embed and execute Wasm modules compiled from any language that targets WebAssembly (TinyGo, Rust, C/C++, AssemblyScript, Zig). Unlike most Wasm runtimes, it has zero external dependencies beyond golang.org/x/sys and never shells out to CGO, so binaries stay statically linked and fully cross-compilable, even to environments without an underlying operating system.

At its core, wazero exposes a small Runtime interface for compiling and instantiating modules, backed by two interchangeable engines: a portable interpreter that runs on any Go-supported architecture, and wazevo, a hand-written ahead-of-time compiler with its own SSA intermediate representation and per-architecture (amd64, arm64) machine-code backends. Both engines pass the official WebAssembly Core 1.0 and 2.0 specification test suites, and wazero ships built-in adapters for WASI preview1, Emscripten, and AssemblyScript host imports so guest modules compiled by common toolchains work out of the box.

What You Get

• A Runtime and ModuleConfig API for compiling, instantiating, and closing WebAssembly modules with fine-grained control over memory limits, filesystem access, and stdio
• Two engine implementations — a portable interpreter and the wazevo ahead-of-time compiler — selected automatically based on platform support, or forced explicitly
• Built-in host module adapters for WASI snapshot preview1, Emscripten, and AssemblyScript so modules built by common toolchains (TinyGo, Emscripten, AssemblyScript) run with minimal glue code
• A compilation cache (wazero.NewCompilationCache) that can be shared across multiple Runtime instances to avoid re-compiling the same module
• NewHostModuleBuilder for exposing arbitrary Go functions to guest modules as host imports
• A standalone wazero CLI (cmd/wazero) for running .wasm binaries directly from the command line

Common Use Cases

• Running untrusted plugin code inside a Go host application in a memory-safe sandbox instead of shelling out to a subprocess
• Executing user-supplied logic (e.g. workflow steps, policy rules, extensions) compiled to Wasm from Rust, TinyGo, or C without adding a CGO build dependency
• Embedding a portable, cross-compilable scripting/extension layer in CLIs and services that must build for many GOOS/GOARCH targets, including scratch containers
• Executing WASI-targeted binaries server-side for edge/serverless-style workloads that need process-like isolation without spawning OS processes

Under The Hood

Architecture The public surface centers on a Runtime interface (runtime.go) that decouples callers from the internal wasm.Store; NewRuntimeWithConfig picks between the wazevo AOT compiler engine and the interpreter engine at construction time via platform.CompilerSupports, and both satisfy a shared internal wasm.Engine contract so the rest of the runtime (module instantiation, host module building, closing) is engine-agnostic. CompileModule decodes and validates the Wasm binary, builds function-type IDs, and hands off to the selected engine’s CompileModule, while InstantiateModule wires up the module’s syscall context, start functions, and close-notifier hooks. Configuration types (RuntimeConfig, ModuleConfig) are immutable interfaces backed by private structs, a pattern the project’s own RATIONALE.md documents as a deliberate choice to keep the public API stable while iterating on internals, and internal packages (internal/wasm, internal/engine/*, internal/sys) are structured specifically to avoid cyclic dependencies.

Tech Stack wazero is pure Go (floor Go version tracked in go.mod) with a single external dependency, golang.org/x/sys, and avoids CGO except for a narrowly scoped, documented case on darwin syscalls. The wazevo compiler engine (internal/engine/wazevo) implements its own SSA-based intermediate representation (ssa/) with a frontend that lowers Wasm bytecode into SSA and per-ISA backends for amd64 and arm64 that emit native machine code directly, without depending on LLVM or any external codegen toolchain. Build and release tooling is Makefile-driven with a large target set, and GitHub Actions workflows (commit.yaml, integration.yaml, examples.yaml, release.yaml) run the suite across OS/arch matrices including scratch-image Docker tests to verify the zero-dependency claim.

Code Quality The repository carries an extensive test suite — roughly 235 _test.go files against 582 Go files overall — including engine-level unit tests, end-to-end tests (e2e_test.go), and a dedicated internal/integration_test tree that runs guest binaries compiled from real toolchains against the runtime. Error handling follows idiomatic Go conventions, wrapping errors with fmt.Errorf and the %w verb, and using a typed sys.ExitError for WASI exit-code propagation rather than swallowing failures. Codecov is wired in via codecov.yml, and CI enforces the test suite on every commit across multiple platforms.

What Makes It Unique Most Go-embeddable Wasm runtimes wrap an existing C or Rust runtime (Wasmtime, Wasmer) through CGO, which breaks static linking and cross-compilation. wazero’s differentiator is its own from-scratch, pure-Go ahead-of-time compiler (wazevo) with hand-written SSA construction and native codegen backends per architecture, letting it claim genuine zero dependencies and CGO-free cross compilation — verified in CI by running its test suite inside a Docker scratch image — while still offering compiler-grade performance rather than falling back to interpretation alone. The project’s RATIONALE.md documents this and dozens of other API and internal design tradeoffs in unusual depth for an open-source runtime.