PyRust Engine

Make your Python code faster by adding one line.

Put @optimize above a function. PyRust turns that function into Rust, compiles it and runs it as native machine code. You keep writing normal Python, and your answers never change: anything PyRust can't run safely runs as normal Python instead.

• ✍️ Write plain Python. No new language, no build step, no rewrite. Type annotations are optional.
• ⚡ Get real speed on calculation-heavy code: arithmetic, math functions, bit operations, helper functions, recursion and NumPy arrays run about 6× to 110× faster in our tests on Linux, macOS and Windows.
• 🧵 Use every CPU core with prange() for loops whose iterations are independent.
• 🛟 Never get a wrong answer. Big integers, math errors, Ctrl-C and anything unsupported fall back to normal Python with the exact same result or exception.
• 🔍 See what's happening. fn.explain() and a one-time warning say which line can't be sped up, why, and how to rewrite it.

📖 Documentation · 🚀 Getting started · 🧩 Examples · 📓 Notebook · 📚 API reference · 🤝 Contributing · 📝 Changelog

import math
import numpy as np
from pyrust_engine import optimize, prange

def distance(x, y):
    return math.sqrt(x * x + y * y)           # plain helper, compiled together with its caller

@optimize
def total_distance(n):
    total = 0.0
    for i in range(n):
        total += distance(float(i), float(n - i))
    return total

@optimize
def mean_and_spread(values):                   # NumPy array in, two values out
    mean = sum(values) / len(values)
    spread = 0.0
    for x in values:
        spread = max(spread, abs(x - mean))
    return mean, spread

@optimize
def transform(values, out) -> int:             # all CPU cores; result identical to Python
    positive = 0
    for i in prange(len(values)):
        out[i] = math.sqrt(abs(values[i])) * 2.0
        if values[i] > 0:
            positive += 1
    return positive

total_distance(300_000)                        # ~64x faster than plain Python on Linux in our benchmark
print(total_distance.explain())                # compiles? if not: which line, why, and a hint

Status: experimental. Not a general Python compiler and not production-hardened. 150 tests pass in CI on Linux, macOS and Windows with Python 3.10 to 3.15.

Comparison at a glance

_{"time · speedup vs Python", measured by CI on a GitHub Actions ubuntu-latest runner (x86_64, Python 3.13, Rust 1.99). Shared CI machines are noisy; treat the numbers as approximate. Raw data: benchmarks/.}

Speed on every platform

Speedup over plain Python, same CI run, Python 3.13 and Rust 1.99:

Float recurrences and math-heavy loops gain less because the floating-point work itself costs the same in both; PyRust removes the interpreter overhead around it. A comparison with Numba is on the benchmarks page.

What compiles

Everything else (lists, dicts, strings, classes, print, try, slicing, …) still runs, as plain Python, and explain() gives a hint. Full details: Guide.

What makes Python slow, and what PyRust does about it

Version comparison

Older releases: Changelog.

Install

pip install "pyrust-engine[arrays]"
python -m pyrust_engine doctor          # checks Python, Rust, the linker, NumPy, and compiles a test function

Without Rust, everything still runs correctly as plain Python, and PyRust shows one warning with the exact fix (including for half-installed toolchains, missing linkers and Jupyter's shorter PATH). See Troubleshooting. On macOS with Homebrew Python, install into a virtual environment first: python3 -m venv ~/pyrust-env && source ~/pyrust-env/bin/activate.

Usage highlights

Arrays: read, write, create

@optimize
def outer(a, b):
    out = np.zeros((len(a), len(b)))
    for i in range(len(a)):
        for j in range(len(b)):
            out[i, j] = a[i] * b[j]
    return out                                 # a new NumPy array

Writes into arrays you pass in go straight to memory with an undo log: if the call fails halfway, the writes are undone and the call replays in Python, so the array ends up exactly as plain Python would leave it.

Recursion and multiple return values

@optimize
def fib(n: int) -> int:                        # recursion needs the return annotation
    return n if n < 2 else fib(n - 1) + fib(n - 2)

@optimize
def fib_pair(n):
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a, b

Parallel loops

prange() is range() in plain Python. Under PyRust it splits iterations across CPU cores, but only for patterns whose result is exactly the sequential one: each iteration writes its own element (out[i] = ...), and the only shared updates are += on int totals. Anything else is rejected with an explanation (float totals depend on the order of additions).

Diagnostics

fn.explain()        # compiles or not; the line, reason and a hint; types it was compiled for
fn.report()         # calls, native/fallback counts, fallback reasons, specializations, long calls
fn.rust_source()    # the generated Rust

PyRustFallbackWarning: simulate ran as plain Python: simulate, line 14: unsupported expression: `[x, y]`
  hint: Lists aren't compiled. Pass a NumPy array (F64Array / I64Array), create one with np.zeros(n), or use separate variables.

In Jupyter: %load_ext pyrust_engine, then %pyrust_check fn and %pyrust_benchmark fn(args).

Deploy without Rust

python -m pyrust_engine build mypackage/kernels.py     # writes mypackage/__pyrust__/ (+ manifest.json)

Ship the __pyrust__/ folder with your package. Machines without Rust load the prebuilt libraries (matched by platform and generated code, verified by SHA-256). See Deployment.

Options

@optimize(fallback=False)            # raise OptimizationError instead of running as Python
@optimize(max_iterations=10**9)      # hard limit; default None = unlimited, Ctrl-C works
@optimize(native_loop_free=True)     # compile tiny loop-free functions too
@optimize(warn_on_fallback=False)    # silence PyRustFallbackWarning
@optimize(timing=True)               # record native/fallback timings in report()

Why it exists

Most "make Python fast" tools ask you to give something up: a new interpreter, a build step, a different integer model, or a heavy dependency. PyRust takes a narrower bet:

• Correctness first. Integers stay arbitrary-precision; overflow, division by zero, bounds, math domain errors and anything unexpected stop the native call, undo its array writes and replay the original Python function, so you get exactly Python's result or exception.
• Opt-in, per function. Decorate the hot function, leave everything else alone.
• Light footprint. Pure-Python package with no runtime dependencies. Uses rustc directly through ctypes: no PyO3, Maturin or crates.

Limitations

• Numeric subset only. No lists, dicts, sets, strings, classes, methods, closures, generators, try/with, slicing or print in compiled code (they run as Python).
• min/max over mixed int and float, round(x, ndigits) and math.hypot aren't compiled (Python's results depend on details native code can't match exactly).
• NumPy scalars: in Python, a[i] gives np.float64; PyRust returns a plain float with the same value.
• Recursion needs a return annotation and runs natively up to 300 levels deep.
• Per-call overhead of about 2–3 µs for native calls (via ctypes). Loop-free functions skip it; loops with tiny inputs don't.
• First call compiles (0.1–0.5 s, cached on disk). Use fn.prepare() or ship prebuilt libraries.
• Arrays: 1-D and 2-D, C-contiguous float64 / int64 only.
• prange only accepts independent iterations (see above).
• Experimental. Not production-hardened and not a sandbox: only run trusted code.

Correctness evidence

• 150 automated tests, passing on Linux, macOS and Windows with Python 3.10, 3.12, 3.13, 3.14 and 3.15 (15 CI jobs), plus lint (ruff), type checks (mypy) and a package build check on every push.
• Edge cases for every operation: NaN, ±0.0, ±inf, overflow, math domain errors, huge exponents and shifts, int/float comparisons around 253 and 263, writes that fail halfway, overlapping and read-only arrays, recursion depth, Ctrl-C on long calls, prebuilt libraries without Rust.
• Generated-program fuzzing: random programs using the supported operators and math functions are compiled and compared with CPython on all three operating systems, including which exception is raised.
• Benchmark tracking: every CI job compares its speedups with the last release and flags drops in the job summary.

Details: VALIDATION.md.

How it works

your function ─► AST check, per argument types ─► Rust source (checked int ops, exact float rules)
   ─► rustc (cached on disk, or a prebuilt library) ─► ctypes call
   ─► status 0: return the result
   ─► status ≠ 0 (overflow, ÷0, bounds, math error, panic, ...): undo array writes, replay in Python
   ─► more than 50M steps: re-run in a background thread with no limit (Ctrl-C stops it)

Generated Rust never contains raw user text: identifiers are mapped to internal names and only allowed AST nodes are translated.

Safety

• Run trusted code only. Compiled libraries run inside your process; this is not a sandbox.
• Keep the cache private (it must be owned by you and not group/world-writable on POSIX).
• Don't change arrays, function code or globals from another thread while a call is running.

Project layout

pyrust_engine/   compiler.py (Python AST → Rust), runtime.py (decorator, dispatch), cache.py,
                 toolchain.py (Rust detection, doctor), prebuilt.py (ahead-of-time builds),
                 ipython.py (Jupyter magics), profiling.py, __main__.py (CLI), py.typed
tests/           test_engine.py, test_v2.py … test_v7.py, test_toolchain.py, test_fuzz.py
examples/        pyrust_vs_python.ipynb, benchmark_suite.py, workloads.py
benchmarks/      raw results per release and platform, compare.py (regression report)
docs/            documentation website (MkDocs), API.md, benchmark chart

Roadmap

1. Faster calls: a CPython extension entry point instead of ctypes, to bring the 2–3 µs per native call well under 1 µs.
2. Typed lists (list[float] arguments) and local tuples as values.
3. More array types: float32, int32, bool, and 3-D arrays.
4. Faster dense array writes (an optimised path for functions that fill whole arrays).
5. Benchmarks on ARM Linux, and against Cython and PyPy.

License

MIT © 2026 Suraj Mhaske