1# wazero: the zero dependency WebAssembly runtime for Go developers
2
3[](https://pkg.go.dev/github.com/tetratelabs/wazero) [](https://opensource.org/licenses/Apache-2.0)
4
5WebAssembly is a way to safely run code compiled in other languages. Runtimes
6execute WebAssembly Modules (Wasm), which are most often binaries with a `.wasm`
7extension.
8
9wazero is a WebAssembly Core Specification [1.0][1] and [2.0][2] compliant
10runtime written in Go. It has *zero dependencies*, and doesn't rely on CGO.
11This means you can run applications in other languages and still keep cross
12compilation.
13
14Import wazero and extend your Go application with code written in any language!
15
16## Example
17
18The best way to learn wazero is by trying one of our [examples](examples/README.md). The
19most [basic example](examples/basic) extends a Go application with an addition
20function defined in WebAssembly.
21
22## Runtime
23
24There are two runtime configurations supported in wazero: _Compiler_ is default:
25
26By default, ex `wazero.NewRuntime(ctx)`, the Compiler is used if supported. You
27can also force the interpreter like so:
28```go
29r := wazero.NewRuntimeWithConfig(ctx, wazero.NewRuntimeConfigInterpreter())
30```
31
32### Interpreter
33Interpreter is a naive interpreter-based implementation of Wasm virtual
34machine. Its implementation doesn't have any platform (GOARCH, GOOS) specific
35code, therefore _interpreter_ can be used for any compilation target available
36for Go (such as `riscv64`).
37
38### Compiler
39Compiler compiles WebAssembly modules into machine code ahead of time (AOT),
40during `Runtime.CompileModule`. This means your WebAssembly functions execute
41natively at runtime. Compiler is faster than Interpreter, often by order of
42magnitude (10x) or more. This is done without host-specific dependencies.
43
44### Conformance
45
46Both runtimes pass WebAssembly Core [1.0][7] and [2.0][14] specification tests
47on supported platforms:
48
49| Runtime | Usage | amd64 | arm64 | others |
50|:-----------:|:--------------------------------------:|:-----:|:-----:|:------:|
51| Interpreter | `wazero.NewRuntimeConfigInterpreter()` | ✅ | ✅ | ✅ |
52| Compiler | `wazero.NewRuntimeConfigCompiler()` | ✅ | ✅ | ❌ |
53
54## Support Policy
55
56The below support policy focuses on compatibility concerns of those embedding
57wazero into their Go applications.
58
59### wazero
60
61wazero's [1.0 release][15] happened in March 2023, and is [in use][16] by many
62projects and production sites.
63
64We offer an API stability promise with semantic versioning. In other words, we
65promise to not break any exported function signature without incrementing the
66major version. This does not mean no innovation: New features and behaviors
67happen with a minor version increment, e.g. 1.0.11 to 1.2.0. We also fix bugs
68or change internal details with a patch version, e.g. 1.0.0 to 1.0.1.
69
70You can get the latest version of wazero like this.
71```bash
72go get github.com/tetratelabs/wazero@latest
73```
74
75Please give us a [star][17] if you end up using wazero!
76
77### Go
78
79wazero has no dependencies except Go, so the only source of conflict in your
80project's use of wazero is the Go version.
81
82wazero follows the same version policy as Go's [Release Policy][10]: two
83versions. wazero will ensure these versions work and bugs are valid if there's
84an issue with a current Go version.
85
86Additionally, wazero intentionally delays usage of language or standard library
87features one additional version. For example, when Go 1.29 is released, wazero
88can use language features or standard libraries added in 1.27. This is a
89convenience for embedders who have a slower version policy than Go. However,
90only supported Go versions may be used to raise support issues.
91
92### Platform
93
94wazero has two runtime modes: Interpreter and Compiler. The only supported operating
95systems are ones we test, but that doesn't necessarily mean other operating
96system versions won't work.
97
98We currently test Linux (Ubuntu and scratch), MacOS and Windows as packaged by
99[GitHub Actions][11], as well as nested VMs running on Linux for FreeBSD, NetBSD,
100OpenBSD, DragonFly BSD, illumos and Solaris.
101
102We also test cross compilation for many `GOOS` and `GOARCH` combinations.
103
104* Interpreter
105 * Linux is tested on amd64 (native) as well arm64 and riscv64 via emulation.
106 * Windows, FreeBSD, NetBSD, OpenBSD, DragonFly BSD, illumos and Solaris are
107 tested only on amd64.
108 * macOS is tested only on arm64.
109* Compiler
110 * Linux is tested on amd64 (native) as well arm64 via emulation.
111 * Windows, FreeBSD, NetBSD, DragonFly BSD, illumos and Solaris are
112 tested only on amd64.
113 * macOS is tested only on arm64.
114
115wazero has no dependencies and doesn't require CGO. This means it can also be
116embedded in an application that doesn't use an operating system. This is a main
117differentiator between wazero and alternatives.
118
119We verify zero dependencies by running tests in Docker's [scratch image][12].
120This approach ensures compatibility with any parent image.
121
122-----
123wazero is a registered trademark of Tetrate.io, Inc. in the United States and/or other countries
124
125[1]: https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/
126[2]: https://www.w3.org/TR/2022/WD-wasm-core-2-20220419/
127[4]: https://github.com/WebAssembly/meetings/blob/main/process/subgroups.md
128[5]: https://github.com/WebAssembly/WASI
129[6]: https://pkg.go.dev/golang.org/x/sys/unix
130[7]: https://github.com/WebAssembly/spec/tree/wg-1.0/test/core
131[9]: https://github.com/tetratelabs/wazero/issues/506
132[10]: https://go.dev/doc/devel/release
133[11]: https://github.com/actions/virtual-environments
134[12]: https://docs.docker.com/develop/develop-images/baseimages/#create-a-simple-parent-image-using-scratch
135[13]: https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md
136[14]: https://github.com/WebAssembly/spec/tree/d39195773112a22b245ffbe864bab6d1182ccb06/test/core
137[15]: https://tetrate.io/blog/introducing-wazero-from-tetrate/
138[16]: https://wazero.io/community/users/
139[17]: https://github.com/tetratelabs/wazero/stargazers