KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

cargo-wasix

★ 63 Open GitHub ↗

Cargo wrapper for working with Webassembly wasi(x).

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# cargo-wasix

A cargo subcommand that wraps regular cargo commands for compiling Rust code
to `wasix`, a superset of Webassembly `wasi` with additional functionality.

See [wasix.org](https://wasix.org) for more.

## Installation

> **Installation requires**
> ‣ [Rust](https://www.rust-lang.org/tools/install) installed via [rustup](https://rustup.rs/)

### Information

This subcommand is available on [crates.io](https://crates.io/crates/cargo-wasix)

Available platforms:

- `x86_64-unknown-linux-gnu`
- `x86_64-apple-darwin`
- `aarch64-apple-darwin`
- `x86_64-pc-windows-msvc`

<br />

> [!WARNING]
> The installation methods below will not immediately install the `wasix` Rust toolchain.
Instead, the toolchain will automatically be downloaded on demand when you run commands like `cargo wasix {check,build,...}`.

<br />

You can install this Cargo subcommand via:

### Cargo Install

```shell
$ cargo install cargo-wasix
```

### Cargo Binstall

> [`cargo binstall`](https://github.com/cargo-bins/cargo-binstall) provides a low-complexity mechanism for installing rust binaries as an alternative to building from source (via `cargo install`) or manually downloading packages.

> Uses pre-built binaries.

```shell
$ cargo binstall cargo-wasix
```

### Install from install script

> Uses pre-built binaries.

#### For Linux and macOS

```shell
$ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/wasix-org/cargo-wasix/releases/latest/download/cargo-wasix-installer.sh | sh
```

#### For Windows

```shell
irm https://github.com/wasix-org/cargo-wasix/releases/latest/download/cargo-wasix-installer.ps1 | iex
```

### Verify Installation

```shell
$ cargo wasix --version
```

### GitHub Actions

Install `cargo-wasix` and the WASIX toolchain in CI using the composite action
published from this repository. Rust and rustup must already be on `PATH` (e.g.
via [`dtolnay/rust-toolchain`](https://github.com/dtolnay/rust-toolchain)).

Minimal example:

```yaml
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- uses: wasix-org/cargo-wasix@v0.1.27
- run: cargo wasix build
```

The action ref determines the default `cargo-wasix` version — `uses:
wasix-org/cargo-wasix@v0.1.27` installs `0.1.27` without an explicit
`with.version`. Prefer tagged refs for reproducible CI.

#### Inputs

| Input | Required | Default | Description |
| --- | --- | --- | --- |
| `version` | no | `""` | crates.io version of `cargo-wasix`. Empty uses the `version` from `Cargo.toml` at the action ref. |
| `toolchain-version` | no | `""` | WASIX Rust toolchain tag (e.g. `v2026-06-09.1+rust-1.90`). Empty downloads the latest toolchain. |
| `locked` | no | `"true"` | Pass `--locked` to `cargo install`. |

#### Full example

```yaml
name: CI

on: [push, pull_request]

jobs:
  wasix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: wasix-org/cargo-wasix@v0.1.27
        with:
          version: "0.1.27"
          toolchain-version: v2026-06-09.1+rust-1.90
          locked: "true"
      - run: cargo wasix build
      - run: cargo wasix test
```

## Usage

The `cargo wasix` subcommand is a thin wrapper around `cargo` subcommands,
providing optimized defaults for the `wasm32-wasmer-wasi` target. Using `cargo wasix`
looks very similar to using `cargo`:

- `cargo wasix build` — build your code in debug mode for the wasix target.

- `cargo wasix build --release` — build the optimized version of your `*.wasm`.

- `cargo wasix run` — execute a binary.

- `cargo wasix test` — run your tests in `wasm32-wasmer-wasi`.

- `cargo wasix bench` — run your benchmarks in `wasm32-wasmer-wasi`.

In general, if you'd otherwise execute `cargo foo --flag` you can likely execute
`cargo wasix foo --flag` and everything will "just work" for the `wasm32-wasmer-wasi`
target.

To give it a spin yourself, try out the hello-world versions of programs!

```
$ cargo new wasix-hello-world
     Created binary (application) `wasix-hello-world` package
$ cd wasix-hello-world
$ cargo wasix run
   Compiling wasix-hello-world v0.1.0 (/code/wasix-hello-world)
    Finished dev [unoptimized + debuginfo] target(s) in 0.15s
     Running `cargo-wasix target/wasm32-wasmer-wasi/debug/wasix-hello-world.wasm`
     Running `target/wasm32-wasmer-wasi/debug/wasix-hello-world.wasm`
Hello, world!
```

Or a library with some tests:

```
$ cargo new wasix-hello-world --lib
     Created library `wasix-hello-world` package
$ cd wasix-hello-world
$ cargo wasix test
   Compiling wasix-hello-world v0.1.0 (/code/wasix-hello-world)
    Finished dev [unoptimized + debuginfo] target(s) in 0.19s
     Running target/wasm32-wasmer-wasi/debug/deps/wasix_hello_world-9aa88657c21196a1.wasm
     Running `/code/wasix-hello-world/target/wasm32-wasmer-wasi/debug/deps/wasix_hello_world-9aa88657c21196a1.wasm`

running 1 test
test tests::it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
```

### Update/re-download the toolchain

If your toolchain stops working, or you want to update to the latest version,
you can run the following command to re-download the lastest release:

```
cargo wasix download-toolchain
```

## License

This project is license under the Apache 2.0 license with the LLVM exception.
See [LICENSE](https://github.com/wasix-org/cargo-wasix/blob/main/LICENSE) for more details.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this project by you, as defined in the Apache-2.0 license,
shall be licensed as above, without any additional terms or conditions.

cargo-wasix

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README