maturin Build Fails - Rust Toolchain or PyO3 Errors in CI

By Kaveh Alemi·Latchkey

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

Diagnose it: is it the build backend or a missing system library?

Python packaging failures in CI split into build-backend configuration problems and missing system headers. The traceback usually points at the backend even when the real cause is an absent -dev package.

python -m pip install --upgrade pip build
python -m build --wheel 2>&1 | tail -40

# a compiler error naming a .h file is a system dependency, not a Python one
#   e.g. "Python.h: No such file" -> python3-dev
#        "openssl/ssl.h"          -> libssl-dev

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.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation