Can Rust and Python Work Together: A Practical Guide

Explore how Rust and Python can interoperate using PyO3 and embedding CPython, with step-by-step how-to, packaging tips, and best practices for 2026 by Corrosion Expert.

Corrosion Expert Team

March 4, 2026·5 min read

Corrosion Expert

Interoperability landscape: why Rust and Python pair well

The combination of Rust's safety and performance with Python's simplicity makes them a powerful duo for many projects. When you ask can rust and python work together, the answer is yes—there are mature, well-supported paths to integrate the two languages. Popular approaches include PyO3, which lets you write Python extensions in Rust, and embedding CPython inside a Rust program to run Python code directly. For data-heavy workloads, Rust handles compute while Python orchestrates workflows. According to Corrosion Expert, the integration pattern you choose should balance runtime performance with development ergonomics, keeping maintenance in mind.

Rust

// Minimal PyO3 example: expose a Rust function to Python
use pyo3::prelude::*;
use pyo3::wrap_pyfunction;

#[pyfunction]
fn add(a: i64, b: i64) -> PyResult<i64> {
    Ok(a + b)
}

#[pymodule]
fn rust_py_bridge(_py: Python, m: &PyModule) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(add, m)?)?;
    Ok(())
}

PyO3 provides decorators and tooling to map Rust types to Python equivalents, with automatic reference counting and GIL management. This enables clean, safe exposure of high-performance code to Python.

Python

# Python usage: import the compiled extension and call a Rust function
import rust_py_bridge
print(rust_py_bridge.add(2, 3))

This approach keeps Python code simple and lets Rust handle heavy lifting. A second, equally valid pattern is embedding Python in Rust to run Python scripts or libraries from a Rust process, which is ideal when Python tooling orchestrates a larger Rust-based system.

formatBlockLengthHintForEditor":170}

Bridge 1: PyO3 — exposing Rust to Python

PyO3 is the most popular route for creating Python modules with Rust. It maps Python objects to Rust types, handles the GIL, and integrates with maturin for packaging. The typical workflow is to write Rust code, annotate with PyO3 macros, build a Python wheel, and then import the module from Python. This block shows how to define a function in Rust and expose it as a Python callable, followed by how to use it from Python.

Rust

// Cargo.toml dependencies snippet (excerpt)
[dependencies]
pyo3 = { version = "0.17", features = ["extension-module"] }

Rust

// Rust source: lib.rs
use pyo3::prelude::*;

#[pyfunction]
fn mul(a: i64, b: i64) -> i64 { a * b }

#[pymodule]
fn math_ext(_py: Python, m: &PyModule) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(mul, m)?)?;
    Ok(())
}

Python

# Python usage after building the wheel
import math_ext
print(math_ext.mul(6, 7))

This pattern keeps a clear boundary: Python as the consumer, Rust as the provider.
Maturin (or setuptools-rust) automates building wheels that can be installed via pip.
Version compatibility of Python and Rust crates is crucial; prefer a pinned PyO3 + maturin version matrix to avoid surprises.

Common variations include exposing a class-based API, returning NumPy arrays efficiently, or using PyO3 to wrap Rust structs as Python classes for more complex data models.

formatBlockLengthHintForEditor":170}

Bridge 2: Embedding Python in Rust

Embedding CPython inside Rust is the complementary approach: instead of exposing Rust functions to Python, you run Python code from Rust to leverage Python libraries, or to script Rust workflows with Python glue. This pattern is particularly useful when you want Python as the orchestration layer while Rust provides computational kernels. Below is a simple example of creating a Python interpreter in Rust and executing a small Python snippet.

Rust

use pyo3::prelude::*;

fn main() -> PyResult<()> {
    Python::with_gil(|py| {
        let sys = py.import("sys")?;
        let version: String = sys.get("version")?.extract()?;
        println!("Python version: {}", version);
        let builtins = py.import("builtins")?;
        let print = builtins.get("print")?;
        print.call1(("Hello from embedded Python!",))?;
        Ok(())
    })
}

Python

# Optional Python script that could be run from Rust
def greet(name):
    return f"Hello, {name}!"

print(greet("Rustacean"))

Embedding requires careful handling of the GIL and reference lifetimes. The embedded Python environment may access Rust libraries, but you should explicitly control what Python code can do in order to maintain safety and performance. Debugging tips include printing Python exception traces and validating input types before crossing the FFI boundary. The embeddings approach is powerful when Python acts as a high-level controller around Rust computations.

formatBlockLengthHintForEditor":180}

Data types and conversions: bridging Rust and Python types

A frequent source of bugs is mismatched data types across Rust and Python boundaries. PyO3 provides robust conversions, but you still need to be mindful of ownership, lifetimes, and error handling. This section shows how to safely convert common types (integers, strings, lists) and how to handle optional values. Code examples illustrate how to pass a Rust Vec<i32> to Python as a list, and how to convert a Python list back to a Rust Vec<i32> with validation.

Rust

use pyo3::prelude::*;
use pyo3::types::PyList;

#[pyfunction]
fn sum_list(py: Python, data: &PyList) -> PyResult<i64> {
    let mut acc: i64 = 0;
    for item in data.iter() {
        let val: i64 = item.extract()?;
        acc += val;
    }
    Ok(acc)
}

Python

# Python side: build a list and pass to Rust
import numpy as np  # if desired for performance, but a plain list works too
from math_ext import sum_list
vals = [1, 2, 3, 4, 5]
print(sum_list(vals))  # 15

Using FromPyObject and IntoPy traits makes conversions ergonomic but requires careful error handling.
When returning complex structures, consider serializing to JSON or using binary formats like MessagePack to minimize crossing costs.
For NumPy-heavy workloads, consider returning NumPy arrays via PyO3's PyArray bridge or using ndarray on the Rust side and exposing a Python-friendly view.

"can rust and python work together" often hinges on choosing the right data boundary strategy and validating inputs at the edge to prevent panics and leaks.

formatBlockLengthHintForEditor":190}

Packaging and distribution: maturin, wheels, and CI

Packaging Rust-powered Python extensions for distribution is a common stumbling block for new projects. The recommended workflow uses maturin to build CPython wheels that are platform-specific. This block demonstrates a minimal packaging pipeline, including a sample pyproject.toml, and commands to build and install locally. By aligning your packaging with standard Python tooling, you simplify CI integration and user installation.

TOML

# pyproject.toml (excerpt)
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "maturin.api"

[tool.maturin]
# optional: specify a specific Python version for wheels

Bash

# Install maturin
pip install maturin

# Build and install the wheel locally (in the active environment)
maturin develop

# Alternatively, build a wheel for distribution
maturin build

Ensure that your Rust crate includes PyO3 as an extension module and that the module name matches the Python import name.
Tests should run against the installed wheel to catch packaging issues early.
CI runners should install the same Python version as your target audience to avoid ABI mismatches.

For cross-platform development, consider using GitHub Actions with a matrix of Python versions and OSes to validate wheels across CPython variants. The end result is a Python package that can be installed with pip, bringing Rust-driven performance to Python projects.

formatBlockLengthHintForEditor":180}

Performance and safe concurrency considerations

Rust brings performance and safety guarantees that are tempting to bolt onto Python projects. However, interpreting languages and FFI boundaries introduce overhead. Profiling both sides is essential to determine if the Rust-Python boundary is a bottleneck. This section demonstrates a tiny micro-benchmark comparing a Rust-implemented function to a pure Python equivalent, illustrating how to measure overhead and decide when to optimize.

Rust

// Simple Rust function for benchmarking
#[pyfunction]
fn heavy_calc(n: usize) -> usize {
    (0..n).fold(0, |acc, x| acc + x)
}

Bash

# Simple micro-benchmark: Python side calling Rust function repeatedly
python - <<'PY'
import time
import heavy_module  # compiled Rust extension
start = time.time()
for _ in range(1000000):
    heavy_module.heavy_calc(100)
end = time.time()
print('Elapsed:', end - start)
PY

In long-running tasks, the GIL can be a limiting factor for Python threads; consider releasing the GIL in Rust for heavy computations. PyO3 provides gil management constructs to help.
When moving large data structures, streaming data across the boundary can reduce overhead compared to transferring full objects.
Benchmark early with realistic workloads; premature optimization can complicate maintenance. The Corrosion Expert analysis suggests focusing on algorithms and memory locality first, then optimizing cross-language boundaries as needed.

formatBlockLengthHintForEditor":180}

Alternatives and trade-offs: choosing the right path

There are several ways to combine Rust and Python, and your choice depends on the problem domain. The most common options are: exposing Rust as a Python extension (PyO3), embedding Python to run scripts from Rust, or using a message-passing interface for distributed systems where Python handles orchestration and Rust handles compute. Each approach has trade-offs:

PyO3 extensions often provide the simplest, most idiomatic integration for Python users and distribution via wheels.
Embedding Python in Rust gives you Java-like control over Python execution at runtime, but adds complexity in error handling and isolation.
A microservice boundary with REST or gRPC allows independence and scaling but requires inter-process communication over the network.

A practical rule: choose PyO3 for Python-accessible libraries, embedding when Python scripts control Rust pipelines, and external services for multi-language scaling. Corrosion Expert recommends starting with PyO3 to validate performance gains before introducing embedding or service boundaries.

formatBlockLengthHintForEditor":150}

Common pitfalls and debugging tips

Inter-language debugging can be tricky. Start with clear error propagation: convert Python exceptions to Rust errors with meaningful messages, and ensure Rust panics don’t crash the Python interpreter. Common issues include lifetime mismatches, incorrect type conversions, and mismatched Python versions. This block shows practical debugging steps and safe-fallback patterns.

Rust

use pyo3::exceptions;
use pyo3::prelude::*;

#[pyfunction]
fn risky_div(a: i64, b: i64) -> PyResult<i64> {
    if b == 0 { Err(exceptions::PyValueError::new_err("division by zero")) } else { Ok(a / b) }
}

Bash

# Quick Python test that surfaces errors clearly
python - <<'PY'
import pytest
import sys
import heavy_module
try:
    heavy_module.risky_div(5, 0)
except Exception as e:
    print('Caught:', type(e).__name__, e)
PY

Always run a small suite of tests that cover boundary values (min, max, nulls).
Enable verbose logging around FFI calls and consider using sanitizers during Rust development.
Maintain a clean API surface; avoid exposing raw pointers or unsafe functions to Python unless absolutely necessary. This approach minimizes crash surface and speeds up debugging, aligning with Corrosion Expert’s best practices.

formatBlockLengthHintForEditor":180}

Step-by-step: a practical 6-step path to Rust-Python interop

{ "steps": [ {"number":1, "title":"Set up the Rust crate","description":"Create a new library crate that will hold the Python bindings. Ensure you have Rust toolchain installed and set up a project structure ready for PyO3 integration.","tip":"Start with a small, self-contained function to validate the bridge without adding complexity."},{"number":2,"title":"Add PyO3 bindings","description":"Add PyO3 as a dependency and annotate a few Rust functions with #[pyfunction] and #[pymodule]. This confirms the language bridge works end-to-end.","tip":"Pin PyO3 version combinations to maintain compatibility with Python versions in your CI."},{"number":3,"title":"Build a Python wheel","description":"Configure maturin (or setuptools-rust) and build a wheel that Python can install. This step ensures packaging correctness.","tip":"Test wheel installation in a clean virtual environment to catch packaging issues."},{"number":4,"title":"Test Python usage","description":"Import the compiled extension in Python and call the exposed Rust functions. Verify type conversions and error handling.","tip":"Add unit tests in Python that exercise edge cases with invalid inputs."},{"number":5,"title":"Explore embedding (optional)","description":"If embedding, write Rust code that initializes CPython, executes a snippet, and captures output. This demonstrates alternative integration patterns.","tip":"Be mindful of GIL scope to avoid unnecessary locking overhead."},{"number":6,"title":"Iterate and document","description":"Add more functions, handle complex data types, and document the API. Prepare a quick-start guide for developers.","tip":"Maintain a minimal, stable interface to reduce maintenance burden."}],"estimatedTime":"60-120 minutes"}

prerequisitesThis field is intentionally left as a structured object in the final output.

← More in Rust Tools & Hardware