maturin Build Fails - Rust Toolchain or PyO3 Errors in CI

maturin compiles a Rust crate (usually via PyO3) into a Python extension. The build needs a Rust toolchain (cargo/rustc) and the right Python development setup; a missing toolchain or an ABI mismatch fails the wheel build.

What this error means

A pip install of a maturin-backed package, or a maturin build, fails with cargo: command not found, a rustc error, or a PyO3 linkage error. No prebuilt wheel exists for this platform, so maturin tried to compile.

💥 maturin failed
  Caused by: Failed to run `cargo rustc`
  Caused by: No such file or directory (os error 2): cargo

Common causes

Rust toolchain not installed

maturin needs cargo and rustc on PATH. A bare runner without rustup has neither, so the compile cannot start.

No prebuilt wheel for this platform/Python

With no compatible wheel on the index, pip builds from source via maturin - which then requires the full Rust toolchain.

How to fix it

Install the Rust toolchain

Provision rustup so cargo/rustc are available, then build.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
. "$HOME/.cargo/env"
pip install <maturin-backed-package>

Prefer a prebuilt wheel where one exists

If the project publishes wheels, force a binary install to skip the Rust compile entirely.

python -m pip install --upgrade pip
pip install --only-binary :all: <package>

How to prevent it

• Bake rustup into images that build Rust extensions.
• Prefer wheels (--only-binary) and a current pip in CI.
• Pin Python to a version with wheel coverage for the extension.

Related guides