1# wazero: the zero dependency WebAssembly runtime for Go developers
2
3[](https://github.com/tetratelabs/wazero/actions/workflows/spectest.yaml) [](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
44If interested, check out the [RATIONALE.md][8] and help us optimize further!
45
46### Conformance
47
48Both runtimes pass WebAssembly Core [1.0][7] and [2.0][14] specification tests
49on supported platforms:
50
51| Runtime | Usage | amd64 | arm64 | others |
52|:-----------:|:--------------------------------------:|:-----:|:-----:|:------:|
53| Interpreter | `wazero.NewRuntimeConfigInterpreter()` | ✅ | ✅ | ✅ |
54| Compiler | `wazero.NewRuntimeConfigCompiler()` | ✅ | ✅ | ❌ |
55
56## Support Policy
57
58The below support policy focuses on compatability concerns of those embedding
59wazero into their Go applications.
60
61### wazero
62
63wazero's [1.0 release][15] happened in March 2023, and is [in use][16] by many
64projects and production sites.
65
66We offer an API stability promise with semantic versioning. In other words, we
67promise to not break any exported function signature without incrementing the
68major version. This does not mean no innovation: New features and behaviors
69happen with a minor version increment, e.g. 1.0.11 to 1.2.0. We also fix bugs
70or change internal details with a patch version, e.g. 1.0.0 to 1.0.1.
71
72You can get the latest version of wazero like this.
73```bash
74go get github.com/tetratelabs/wazero@latest
75```
76
77Please give us a [star][17] if you end up using wazero!
78
79### Go
80
81wazero has no dependencies except Go, so the only source of conflict in your
82project's use of wazero is the Go version.
83
84wazero follows the same version policy as Go's [Release Policy][10]: two
85versions. wazero will ensure these versions work and bugs are valid if there's
86an issue with a current Go version.
87
88Additionally, wazero intentionally delays usage of language or standard library
89features one additional version. For example, when Go 1.29 is released, wazero
90can use language features or standard libraries added in 1.27. This is a
91convenience for embedders who have a slower version policy than Go. However,
92only supported Go versions may be used to raise support issues.
93
94### Platform
95
96wazero has two runtime modes: Interpreter and Compiler. The only supported operating
97systems are ones we test, but that doesn't necessarily mean other operating
98system versions won't work.
99
100We currently test Linux (Ubuntu and scratch), MacOS and Windows as packaged by
101[GitHub Actions][11], as well compilation of 32-bit Linux and 64-bit FreeBSD.
102
103* Interpreter
104 * Linux is tested on amd64 (native) as well arm64 and riscv64 via emulation.
105 * MacOS and Windows are only tested on amd64.
106* Compiler
107 * Linux is tested on amd64 (native) as well arm64 via emulation.
108 * MacOS and Windows are only tested on amd64.
109
110wazero has no dependencies and doesn't require CGO. This means it can also be
111embedded in an application that doesn't use an operating system. This is a main
112differentiator between wazero and alternatives.
113
114We verify zero dependencies by running tests in Docker's [scratch image][12].
115This approach ensures compatibility with any parent image.
116
117-----
118wazero is a registered trademark of Tetrate.io, Inc. in the United States and/or other countries
119
120[1]: https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/
121[2]: https://www.w3.org/TR/2022/WD-wasm-core-2-20220419/
122[4]: https://github.com/WebAssembly/meetings/blob/main/process/subgroups.md
123[5]: https://github.com/WebAssembly/WASI
124[6]: https://pkg.go.dev/golang.org/x/sys/unix
125[7]: https://github.com/WebAssembly/spec/tree/wg-1.0/test/core
126[8]: internal/engine/compiler/RATIONALE.md
127[9]: https://github.com/tetratelabs/wazero/issues/506
128[10]: https://go.dev/doc/devel/release
129[11]: https://github.com/actions/virtual-environments
130[12]: https://docs.docker.com/develop/develop-images/baseimages/#create-a-simple-parent-image-using-scratch
131[13]: https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md
132[14]: https://github.com/WebAssembly/spec/tree/d39195773112a22b245ffbe864bab6d1182ccb06/test/core
133[15]: https://tetrate.io/blog/introducing-wazero-from-tetrate/
134[16]: https://wazero.io/community/users/
135[17]: https://github.com/tetratelabs/wazero/stargazers
View as plain text