wazero in Go: what the interpreter and the AOT compiler actually cover
wazero: the zero dependency WebAssembly runtime for Go developers
At a glance
- What is it?
- wazero runs WebAssembly modules inside a Go program with one dependency and no CGO. The engine you never choose, the two-version Go policy and an asymmetric platform grid decide where it can run.
- Who is it for?
- wazero is a good fit when the host program is Go, the guests are untrusted code, and shipping one static binary matters more than peak execution speed. Check two things before adopting it: that your target GOOS and GOARCH appear on the tested list for the engine you intend to enable, and that your Go release sits inside wazero's two-version window with the 1.25.0 floor.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 27 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- wazero/wazero6,469 ★ · +84
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| wazero/wazero | 6.4k | 6.5k |
84 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Two engines behind one Runtime: the compiler by default, the interpreter on request
wazero ships two execution engines behind one Runtime type, and the engine you never pick is the engine you get. `wazero.NewRuntime(ctx)` selects the Compiler whenever the target supports it. Asking for the other one takes a config value:
r := wazero.NewRuntimeWithConfig(ctx, wazero.NewRuntimeConfigInterpreter())The Interpreter is described as a naive interpreter-based implementation of the Wasm virtual machine, and its implementation holds no platform specific code, so it can be used for any compilation target Go offers, riscv64 named as the example. The Compiler goes the other way: it compiles modules into machine code ahead of time, inside `Runtime.CompileModule`, so your Wasm functions execute natively instead of walking an interpreter loop. The stated gap between them is large. The Compiler is called faster than the Interpreter often by an order of magnitude, 10x or more, and the point is made that this happens without host-specific dependencies. Because both engines sit behind the same API, choosing between them is a deployment decision rather than a rewrite, which is why the default matters more here than in runtimes where the engine is fixed at build time.
The conformance grid stops the compiler outside amd64 and arm64
Both engines are run against the WebAssembly Core Specification 1.0 and 2.0 test suites, but the platform grid in the support policy is not symmetrical. The Interpreter row carries a check on amd64, arm64 and other targets. The Compiler row carries checks on amd64 and arm64, and a cross in the others column. That one cell is the practical ceiling on the compiler: a riscv64 Linux build or a 32 bit Windows target has no compiler coverage, and the interpreter becomes the engine you are left with. macOS is tested on arm64 only, so an Intel Mac sits outside the tested set for both engines. Windows, FreeBSD, NetBSD, OpenBSD, DragonFly BSD, illumos and Solaris are tested on amd64 only for the interpreter (OpenBSD is not on the compiler's list), and the BSD and Solaris runs happen inside nested VMs on Linux rather than on native images. Linux is the widest tested surface, on Ubuntu and on a scratch image, and cross compilation is exercised for many GOOS and GOARCH pairs. One more item is named: macOS developers who need to code-sign are pointed to issue #2393 on code-signing entitlements.
Zero dependencies and no CGO are what keep the cross build intact
The dependency list is unusually short. go.mod declares the module as github.com/tetratelabs/wazero with a single require line, golang.org/x/sys v0.44.0, and there is no CGO anywhere in the project. That combination is why the Go version is the only version conflict a consuming program has to think about, and why an application embedding a runtime keeps a plain cross build instead of dragging a C toolchain into its build image. The README goes further and names embedding in an application that does not use an operating system as the main differentiator against alternatives. That is a narrower claim than a speed number, and a more checkable one, because it is about what your binary needs around it. The claim is also verified rather than asserted: the test suite runs inside Docker's scratch image, so a dependency that sneaks in becomes a failing test instead of a surprise in someone else's container. A scratch image carries no libc, no shell and no package manager, so anything needed at build time has to be pure Go. The same property is what lets the compiler emit machine code without host specific dependencies.
The Go floor is 1.25.0 and only two Go versions are supported
wazero pins its toolchain expectation in two places, and both of them bite. The first is go.mod, which declares `go 1.25.0` under a comment describing it as the floor Go version of wazero, written as the current version minus one. The second is the support policy, which says wazero follows the same version policy as Go's own release policy: two versions. In practice a build on a Go release older than that floor is out, and the promise that bugs are valid covers only the current Go versions. The second trap in the same file is a retraction block. All four beta tags from the 1.0.0 line, v1.0.0-beta1 through v1.0.0-beta.3, are retracted, with a note that they are replaced with pre to stop people from upgrading into the broken beta 1. An old lock file pointing at one of those tags is not merely stale, it points at a build the maintainers asked users to leave.
Adding wazero to a Go program and running the example suite
wazero is a Go module, so installation is the single module proxy line the project gives you:
go get github.com/tetratelabs/wazero@latestThere is no binary to download and no code generation step. First use is the Runtime, and the default path is one call:
r := wazero.NewRuntime(ctx)The examples directory is where the rest of the surface shows up. examples/basic extends a Go application with an addition function defined in WebAssembly, and the sibling directories cover allocation, a cli, concurrent instantiation, importing Go functions into Wasm, multiple results, and several runtimes in one process. The Makefile runs all of them, plus the import examples, under a shared test timeout of 300 seconds:
@go test $(go_test_options) ./examples/... ./imports/assemblyscript/example/... ./imports/emscripten/... ./imports/wasi_snapshot_preview1/example/...The guest toolchains are pinned in the same file. The AssemblyScript example builds its own fixture with npm install and npm run build, and the Zig fixtures are produced with zig build using ReleaseSmall, so reproducing the testdata means installing those two toolchains as well.
The semver promise covers exported signatures and stops there
The stability promise is written in one narrow sentence: no exported function signature is broken without a major version increment. The 1.0 release happened in March 2023, and the scheme around it is spelled out with worked examples. New features and behaviour arrive on a minor bump, illustrated as 1.0.11 moving to 1.2.0. Bug fixes and internal details change on a patch bump, illustrated as 1.0.0 moving to 1.0.1. The recent tags follow that shape: v1.12.0 published on 2026-05-29, v1.11.0 on 2025-12-19, and v1.10.1 on 2025-11-11, with the last push to the default branch on 2026-10-19. The repository is not archived. What the promise leaves open is stated far less clearly than what it covers. Because it is scoped to exported function signatures, it does not say how long a deprecated entry point stays around before removal, and the README does not document a deprecation window. It also does not enumerate which packages sit inside the promise, which matters when you read a tree that places api/, internal/, sys/, cmd/ and experimental/ next to each other at the top level.
Gaps the README leaves around host languages, signing and spec coverage
Several limits of this project are absences rather than defects, and the honest way to state them is to name the document that stays quiet. The integration path shown is a Go import: a module path, a Runtime type, and examples written in Go, with no bindings documented for other host languages. If your host is Python, Node or a shell, the bridging work is not described here. Code signing on macOS is the other named gap, tracked in issue #2393. Spec coverage is stated as the Core Specification 1.0 and 2.0 test suites, which is the core test set, and nothing in this README covers the component model or threaded execution, so the conformance claim should not be read as a statement about every proposal in the WebAssembly ecosystem. The Interpreter is described as naive, and it is the engine you get wherever the compiler has no coverage, so behaviour on a riscv64 host would have to be measured by the person deploying it. Finally, the host bindings under imports/ are grouped by toolchain, with directories for AssemblyScript, Emscripten and wasi_snapshot_preview1, and the Makefile exercises only their example suites.
Editorial conclusion
wazero is a good fit when the host program is Go, the guests are untrusted code, and shipping one static binary matters more than peak execution speed. Check two things before adopting it: that your target GOOS and GOARCH appear on the tested list for the engine you intend to enable, and that your Go release sits inside wazero's two-version window with the 1.25.0 floor. Skip it when the host is not Go, when a signed Intel Mac build is the target, or when you need spec coverage beyond the Core 1.0 and 2.0 test suites this project reports.
Frequently asked questions
Does wazero need CGO or any third party Go dependency?
No. Beyond Go itself the only requirement is golang.org/x/sys v0.44.0, and the project does not need CGO, which is what lets it keep cross compilation and run inside an application that does not use an operating system.
When should I pick the wazero interpreter instead of the compiler?
Pick the interpreter when your target is outside the compiler's tested set. The interpreter has no GOOS or GOARCH specific code and works on any compilation target Go supports, riscv64 included, while the compiler is tested only on amd64 and arm64.
How current are the wazero releases?
The three most recent tags are v1.12.0 on 2026-05-29, v1.11.0 on 2025-12-19 and v1.10.1 on 2025-11-11, and the last push to the default branch landed on 2026-10-19. The 1.0 release was in March 2023.
Which Go versions can a project build wazero with?
go.mod declares go 1.25.0 as the floor, commented as the current Go version minus one, and wazero follows Go's two-version release policy. The Go version is therefore the only version conflict for a project that embeds it.
Can I run wazero from a host language other than Go?
The documented path is a Go import: wazero.NewRuntime and the examples are Go, and no bindings for other host languages are documented. For code signing a macOS binary that embeds wazero, the README points to issue 2393.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/wazero-wazero)Star history chart for your README
[](https://hysenlabs.com/projects/wazero-wazero)Was this useful?