wasmtime compile: Ahead-of-Time Wasm Compilation
wasmtime compile turns a WebAssembly module into a serialized native artifact (.cwasm) that later runs without recompilation.
AOT compilation moves the Cranelift work to build time. In CI you compile once, cache the .cwasm, and run it many times with near-zero startup cost.
What it does
wasmtime compile reads a .wasm and emits a .cwasm containing native code for a target. The output is loaded later with wasmtime run --allow-precompiled (or the embedding API), skipping JIT compilation entirely.
Common usage
wasmtime compile app.wasm -o app.cwasm
wasmtime compile --target x86_64-linux app.wasm -o app.cwasm
wasmtime run --allow-precompiled app.cwasmOptions
| Flag | What it does |
|---|---|
| -o <file> | Output path for the compiled .cwasm |
| --target <triple> | Cross-compile for a target triple (e.g. aarch64-linux) |
| -O <opt> | Codegen options via the -O group (e.g. -O opt-level=2) |
| --allow-precompiled (on run) | Permit running a serialized .cwasm |
In CI
A .cwasm is tied to the Wasmtime version and target that produced it. Cache the .cwasm keyed on the runtime version; loading a .cwasm built by a different Wasmtime raises a compatibility error. Cross-compile with --target when the build runner differs from the run environment.
Common errors in CI
"Module was compiled with incompatible Wasmtime version" means the running Wasmtime differs from the one that produced the .cwasm; rebuild or pin the version. "failed to parse WebAssembly module" means the input .wasm is invalid. Running a .cwasm without --allow-precompiled is refused for safety.