跳到主要内容

wasmedge instantiate CLI

After installation, users can execute the wasmedge instantiate command.

The wasmedge instantiate command loads, validates, and instantiates a WebAssembly module. It checks that all imports can be resolved and that the module can be fully instantiated, but does not execute any functions. This is useful for verifying that a WASM module can be successfully linked and instantiated in a given environment before running it.

The wasmedge instantiate command also supports linking additional WASM modules, allowing you to verify that multi-module dependencies resolve correctly.

$ wasmedge instantiate -h
USAGE
   wasmedge instantiate [OPTIONS] [--] WASM_OR_SO

...

Options​

The options of the wasmedge instantiate command are as follows.

  1. -h|--help: Show the help messages. Will ignore the other arguments below.
  2. (Optional) --log-level: Set logging level. Valid values: off, trace, debug, info, warning, error, fatal. Default is info.
  3. (Optional) --forbidden-plugin: List of plugins to ignore.
  4. (Optional) --module: Register additional WASM modules for linking. Each module can be specified as --module name:path, where name is the module name to export and path is the WASM file path. This option can be repeated to register multiple modules.
  5. (Optional) --dir: Bind directories into WASI virtual filesystem.
    • Use --dir guest_path:host_path to bind the host path into the guest path in WASI virtual system.
  6. (Optional) --env: Assign the environment variables in WASI.
    • Use --env ENV_NAME=VALUE to assign the environment variable.
  7. (Optional) --memory-page-limit: Set the limitation of pages (as size of 64 KiB) in every memory instance.
  8. (Optional) WebAssembly proposals:
  9. Input WASM file (/path/to/wasm/file).

Example​

Instantiating a self-contained module​

We created the hand-written fibonacci.wat and used the wat2wasm tool to convert it into the fibonacci.wasm WebAssembly program. It exported a fib() function which takes a single i32 integer as the input parameter.

You can run:

wasmedge instantiate fibonacci.wasm

The output will be:

[2026-03-24 02:07:47.135] [info] Instantiation succeeded.

The exit code will be 0.

Instantiation failure due to unresolved imports​

We created the hand-written bad_instantiate.wat and used the wat2wasm tool to convert it into the bad_instantiate.wasm WebAssembly program. This module imports functions, memory, tables, and globals from an env module that is not available in the CLI environment, causing instantiation to fail.

You can run:

wasmedge instantiate bad_instantiate.wasm

The output will be:

[2026-04-09 00:33:46.404] [error] instantiation failed: unknown import, Code: 0x302
[2026-04-09 00:33:46.404] [error]     When linking module: "env" , memory name: "memory"
[2026-04-09 00:33:46.404] [error]     At AST node: import description
[2026-04-09 00:33:46.404] [error]     This may be the import of host environment like JavaScript or Golang. Please check that you've registered the necessary host modules from the host programming language.
[2026-04-09 00:33:46.404] [error]     At AST node: import section
[2026-04-09 00:33:46.404] [error]     At AST node: module

The exit code will be 1.

Multi-module linking​

You can register additional WASM modules to satisfy imports using the --module option. For example, if main.wasm imports from a module named utils, you can provide it:

wasmedge instantiate --module utils:utils.wasm main.wasm

Multiple modules can be linked by repeating the --module flag:

wasmedge instantiate --module utils:utils.wasm --module math:math.wasm main.wasm

If all imports are resolved successfully, the output will be:

[info] Instantiation succeeded.