Tutorial: Rust Package

Tutorial: Rust Package#

Python packages with Rust extensions — typically built with PyO3 and Maturin — can be cross-compiled for WebAssembly using pyodide-build.

Note

Rust support in pyodide-build requires some manual setup compared to C/C++ packages. You need to install the correct Rust toolchain and Emscripten target yourself.

Prerequisites#

1. Install Rust#

If you don’t have Rust installed, use rustup to install it.

2. Install the correct Rust toolchain (optional)#

Depending on the Pyodide/Python version you’re targeting, you may need a specific Rust toolchain version. This might not be necessary in all cases for Python 3.14 or later, but if you encounter issues, you can try installing the correct toolchain.

Query it with:

pyodide config get rust_toolchain

Install and activate it:

RUST_TOOLCHAIN=$(pyodide config get rust_toolchain)
rustup toolchain install "$RUST_TOOLCHAIN"
rustup default "$RUST_TOOLCHAIN"

3. Add the Emscripten target#

The wasm32-unknown-emscripten target must be available for your Rust toolchain:

RUST_TOOLCHAIN=$(pyodide config get rust_toolchain)
rustup target add wasm32-unknown-emscripten --toolchain "$RUST_TOOLCHAIN"

Build a Rust package#

With the toolchain set up, build your Maturin/PyO3 package:

pyodide build .

pyodide-build sets the following environment variables automatically during the build:

Variable

Value

Purpose

CARGO_BUILD_TARGET

wasm32-unknown-emscripten

Tells Cargo to cross-compile for Emscripten

CARGO_TARGET_WASM32_UNKNOWN_EMSCRIPTEN_LINKER

emcc

Uses Emscripten as the linker

PYO3_CROSS_INCLUDE_DIR

<xbuildenv>/include

PyO3 cross-compilation: Python headers location

PYO3_CROSS_LIB_DIR

<xbuildenv>/lib

PyO3 cross-compilation: Python library location

PYO3_CROSS_PYTHON_VERSION

3.x

PyO3 cross-compilation: target Python version

You don’t need to set these manually — they come from the cross-build environment.

Querying Rust configuration#

Use pyodide config to inspect the Rust-related build settings:

pyodide config get rust_toolchain              # e.g., 1.93.0
pyodide config get rustflags                   # e.g., -C link-arg=-sSIDE_MODULE=2 ...

Limitations#

  • Nightly Rust required — Before Python 3.14, the wasm32-unknown-emscripten target is not available on stable Rust. The specific nightly version must match what pyodide-build expects.

What’s next?#