██████╗ ██╗ ██╗████████╗██╗ ██╗ ██████╗ ███╗ ██╗██████╗ ███████╗
██╔══██╗╚██╗ ██╔╝╚══██╔══╝██║ ██║██╔═══██╗████╗ ██║██╔══██╗██╔════╝
██████╔╝ ╚████╔╝ ██║ ███████║██║ ██║██╔██╗ ██║██████╔╝███████╗
██╔═══╝ ╚██╔╝ ██║ ██╔══██║██║ ██║██║╚██╗██║██╔══██╗╚════██║
██║ ██║ ██║ ██║ ██║╚██████╔╝██║ ╚████║██║ ██║███████║
╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝
[PYTHON, COMPILED TO BYTECODE — rkyv-CACHED ON EVERY RUN, AOT-NATIVE]
"CPython compiles to its own bytecode and walks it. pythonrs lowers Python to a shared machine, caches the result on every run, and can bake a script into a native binary."
pythonrs is Python as a fusevm
frontend — a lexer/parser and compiler that lowers Python 3 to fusevm::Chunk
bytecode running on the fusevm three-tier Cranelift JIT, over a PyHost object
heap. There is no bespoke VM and no bespoke JIT: pythonrs is a pure front end;
execution and codegen live in fusevm — the same engine behind
zshrs,
strykelang,
awkrs,
vimlrs,
elisprs, and
rubylang.
It is, to our knowledge, 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.
Read the Docs · Engineering Report · Builtin Reference
Table of Contents
- [0x00] Overview
- [0x01] Install
- [0x02] Usage
- [0x03] Language Features
- [0x04] Command-Line Flags
- [0x05] Architecture
- [0x06] Parity Harness
- [0x07] Status & Roadmap
- [0x08] Documentation
- [0xFF] License
[0x00] OVERVIEW
pythonrs keeps Python the language and throws away CPython's execution model. It
lexes and parses Python to an AST, lowers the AST to fusevm bytecode, and runs
the bytecode on a stack VM with a Cranelift JIT. Arithmetic and comparisons lower
to native ops; Python-specific behavior — truthiness, str/list concat, bignum
promotion, attribute and method dispatch — runs through a strict numeric hook and
a numbered builtin-call protocol into the PyHost object heap.
Two things set it apart from every other standalone Python:
- Transparent rkyv bytecode cache — on every run.
python foo.pyhashes the source, consults~/.pythonrs/scripts.rkyv, and on a hit runs the compiled chunks directly with lex/parse/lower skipped entirely. No flags, no separate build step, no__pycache__ritual. - AOT to a native executable.
python --build foo.pyemits a standalone native binary (viafusevm::aot, linked against the pythonrs runtime staticlib) that runs the script with no interpreter present.
[0x01] INSTALL
# Via the Homebrew tap (bumped by each release; formula is `pythonrs`)
# Or from source
&&
# binary: target/release/python (+ libpythonrs.a for AOT linking)
Zsh tab completion
# or: fpath=(/path/to/pythonrs/completions $fpath) in .zshrc
[0x02] USAGE
Set PYTHONRS_TRACE=1 to log cache hit/miss to stderr (silent otherwise).
[0x03] LANGUAGE FEATURES
Arbitrary-precision integers, real closures, classes with inheritance, operator
dunders, generators (yield / yield from / lazy generator expressions, backed
by stackful corosensei coroutines), match/case structural pattern matching,
own-scope comprehensions (list/dict/set) and proper nonlocal, f-strings,
exceptions, and full call-site and literal * / ** unpacking. The PyHost
heap implements the str / list / dict / tuple / set / instance object
model with the operator, attribute, item, and iteration protocols. See
[0x07] and BUGS.md for the honest list of
what is not yet implemented.
[0x04] COMMAND-LINE FLAGS
| Flag | Effect |
|---|---|
| (none) | Run the script/one-liner, transparently rkyv-cached. |
--build |
AOT-compile the script to a standalone native executable. |
--dump-bytecode |
Print the lowered fusevm bytecode and exit. |
--repl |
Start the interactive REPL. |
--lsp |
Run the Language Server Protocol server over stdio. |
[0x05] ARCHITECTURE
lexer → parser → AST → compiler → fusevm::Chunk → fusevm VM + JIT
│ │
└── CallBuiltin ─────→ host (PyHost heap)
lexer.rs— indentation-significant tokenizer (INDENT/DEDENT/NEWLINE, f-strings).parser.rs— recursive-descent Python grammar →ast.rs.compiler.rs— lowers the AST to fusevm ops +CallBuiltindispatches.host.rs— thePyHostobject heap (str/list/dict/tuple/set/instances/…), the operator/attribute/item/iteration semantics, and the fusevm run plumbing.builtins.rs— theCallBuiltinhandler table, the numeric hook, the Kernel builtin functions (print/len/range/ …), and per-type methods.cache.rs— the rkyv-shard bytecode cache.aot_native.rs— native-executable emission viafusevm::aot.
[0x06] PARITY HARNESS
Correctness is measured, not asserted: an example corpus runs through both
pythonrs and the reference python3, and the output is diffed byte-for-byte.
pythonrs runs a large, real subset of Python 3, verified against CPython on that
corpus.
Beyond the fixed corpus, the parity-fuzz binary is a differential fuzzer. It
generates thousands of grammar-driven, deterministic-output snippets — biased
toward the historically fragile areas (float repr, integer ///% sign
rules, bignum, slices, the format mini-language, string methods) — runs each
through python -c and the reference python3 -c, and reports every case where
stdout or accept/reject diverges. Each case is seeded, so any divergence is
delta-debugged to a minimal reproducer and replays exactly:
The generator never emits nondeterministic output, so every reported divergence
is a real gap. PYTHONRS_FUZZ_PYTHON names the reference interpreter; a
--baseline allowlist keeps known gaps from failing while new ones exit non-zero.
[0x07] STATUS & ROADMAP
Active, in development. The runtime executes a substantial real subset of Python
3. BUGS.md is the honest ledger of unimplemented features — async,
bytes operations, and most of the standard library are not yet carried. A DAP
debug adapter (--dap), man pages, and the generated reference.html land
alongside the growing builtin surface.
[0x08] DOCUMENTATION
- Docs site — https://menketechnologies.github.io/pythonrs/
- Engineering report — https://menketechnologies.github.io/pythonrs/report.html
- Builtin reference — https://menketechnologies.github.io/pythonrs/reference.html
- The shared VM —
fusevm, also behindzshrs,strykelang,awkrs,vimlrs,elisprs,rubylang.
[0xFF] LICENSE
MIT.