// PYTHONRS — PYTHON IN RUST

What it is

pythonrs runs Python programs as ordinary compiled bytecode: it lexes and parses the source, lowers it to fusevm instructions, and lets the shared engine execute and JIT-compile them. There is no bespoke VM or tree-walker — arithmetic and comparisons lower to native fusevm ops so the Cranelift JIT can trace hot loops, while Python-specific behaviour (truthiness, attribute and method dispatch, str/list concatenation, bignum promotion, object construction) is served by the PyHost object heap.

It is another language hosted on fusevm, the shared bytecode VM and Cranelift JIT behind zshrs (the shell), stryke (the language), awkrs (AWK), elisp (Emacs Lisp), and rubylang (Ruby). pythonrs carries no VM or JIT of its own.

To our knowledge it is the first compiled standalone Python runtime that both transparently caches bytecode via rkyv on every run and AOT-compiles a script to a native executable.

Architecture

The pipeline mirrors how zshrs hosts zsh and rubylang hosts Ruby:

Python source  →  lexer  →  parser (AST)  →  lower to fusevm bytecode  →  fusevm VM + Cranelift JIT
                                                    │
                                          PyHost object heap (str/list/dict/tuple/set/instances)

Example

def fib(n):
    return n if n < 2 else fib(n - 1) + fib(n - 2)

print(", ".join(str(fib(i)) for i in range(11)))
# => 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55

total = 0
for x in [1, 2, 3, 4]:
    total += x
print(total)          # => 10

squares = [n * n for n in range(5)]
print(squares)        # => [0, 1, 4, 9, 16]

print(len({**{"a": 1, "b": 2}}.keys()))   # => 2
print(f"{fib(10):,}")                      # => 55

Status & roadmap

The table below reflects the current state of the tree. See BUGS.md for the honest ledger of what is not yet carried.

Why pythonrs

Cache benchmark

The rkyv shard skips lex/parse/lower on a warm run — including every imported module, which is where the win lands. The gain scales with how much source a run compiles: a tiny import-free script is already sub-parse-time, so warm ≈ cold; a run that pulls in stdlib modules amortizes their compilation once and reads them back from the shard on every later run.

cargo build --release binary, hyperfine -N (80 runs each), isolated cache dir. Cold clears ~/.pythonrs/scripts.rkyv before each run so it pays the full compile plus the shard write; warm is a straight cache hit. The shard is a single content-keyed store shared across concurrent processes (an exclusive flock serializes writers so no entry is lost), deduped by source hash — the 10-import run leaves 21 module entries in a 3.1 MiB shard. Import-free scripts see no benefit by design; the cache pays off precisely when a run compiles real amounts of source.

Building from source

pythonrs builds as a standalone Rust crate (it is not a workspace member of the meta repo):

# clone
git clone https://github.com/MenkeTechnologies/pythonrs
cd pythonrs

# build (release; produces target/release/python + libpythonrs.a)
# the default build links an embedded libpython (the stdlib-ffi bridge),
# so CPython must be present at build time
cargo build --release

# run a script, a one-liner, or the REPL
./target/release/python script.py
./target/release/python -c 'print(sum(range(1, 101)))'
./target/release/python --repl

# diagnostics
./target/release/python --doctor
./target/release/python --cacheview
./target/release/python --tiers script.py

# AOT-compile a script to a native ./script executable
# --build needs the libpython-free runtime; a stdlib-ffi binary refuses up front
cargo build --release --no-default-features
./target/release/python --build script.py

# run tests
cargo test

fusevm is pulled from crates.io with the jit, jit-disk-cache, aot, and ffi features. Set PYTHONRS_TRACE=1 to log cache hit/miss to stderr, or PYTHONRS_CACHE=0 to disable the bytecode cache entirely.

License

pythonrs is MIT licensed — free and open source. See LICENSE.

Repository & links

• Engineering report — report.html (architecture, fusevm hosting, roadmap, dependency posture)
• Builtin reference — reference.html (Kernel builtins and core methods)
• Source — github.com/MenkeTechnologies/pythonrs
• Issues — github.com/MenkeTechnologies/pythonrs/issues
• The shared VM — fusevm (also behind zshrs, stryke, awkrs, elisp, rubylang)