PYRS

AI agent developed Python interpreter in Rust targeting CPython 3.14 semantics.

Quick Start · Installation · Usage · Status · Docs · Contributing

At a Glance

Area	Current State
Compatibility target	CPython 3.14
Core execution paths	REPL/stdin, module (-m), source (.py), and bytecode (.pyc)
Platform priority	Linux (x86_64) and macOS (x86_64, aarch64)
C-extension support	In progress (scientific stack bring-up underway)
Local test runner	cargo nextest run

Quick Start

Install from GitHub Releases (binary, plus bundled CPython 3.14.3 stdlib only when needed). Default channel is nightly:

curl -fsSL https://raw.githubusercontent.com/BlueBlazin/pyrs/master/scripts/install.sh | bash
pyrs --version

The installer writes pyrs to ~/.local/bin. If a usable local CPython 3.14 stdlib is not already present, it also stages the official Lib/ under ${XDG_DATA_HOME:-~/.local/share}/pyrs/stdlib/3.14.3/Lib. When Python 3.14 is already installed, the installer skips the bundled stdlib and reuses the host stdlib instead.

Run interactive REPL:

pyrs

Run inline Python:

pyrs -c "import platform; print(platform.python_version())"

Run a script:

pyrs path/to/script.py

Installation

GitHub one-command installer (recommended)

curl -fsSL https://raw.githubusercontent.com/BlueBlazin/pyrs/master/scripts/install.sh | bash

Published release channel:

curl -fsSL https://raw.githubusercontent.com/BlueBlazin/pyrs/master/scripts/install.sh | bash -s -- --stable

Uninstall:

curl -fsSL https://raw.githubusercontent.com/BlueBlazin/pyrs/master/scripts/install.sh | bash -s -- --uninstall

Cargo install (bring your own CPython stdlib)

cargo install --locked --git https://github.com/BlueBlazin/pyrs --bin pyrs

cargo install only installs the pyrs binary. For full stdlib behavior, ensure CPython 3.14 stdlib is available (or set PYRS_CPYTHON_LIB=/path/to/python3.14/Lib).

Cargo install from local repo path

git clone https://github.com/BlueBlazin/pyrs.git
cd pyrs
cargo install --locked --path .

Build from source (no install)

git clone https://github.com/BlueBlazin/pyrs.git
cd pyrs
cargo build --release
./target/release/pyrs --version

Homebrew (tap)

brew install --HEAD blueblazin/tap/pyrs

This installs the nightly channel as a prebuilt macOS binary rather than compiling PYRS or pulling a Homebrew Rust toolchain. The Homebrew path now fetches both the binary and the bundled stdlib from PYRS GitHub Releases, not directly from python.org. If you want the latest tagged release instead of nightly, drop --HEAD.

Homebrew keeps the bundled stdlib inside the keg under share/pyrs/stdlib/3.14.3/Lib, so it does not reuse or overwrite a system CPython install and is removed by brew uninstall.

Uninstall with:

brew uninstall pyrs

Docker nightly

docker pull ghcr.io/blueblazin/pyrs:nightly
docker run --rm -it ghcr.io/blueblazin/pyrs:nightly

Nightly binary archives (advanced)

Nightly binary archives are published at:

• GitHub Releases (nightly tag)

These archives are binary-only. Use them when CPython 3.14 is already available locally, or when you plan to place the separate pyrs-stdlib-cpython-3.14.3.tar.gz bundle yourself. If you want stdlib placement handled automatically, use the GitHub installer or Homebrew.

Usage

CLI execution modes

pyrs                         # REPL (or stdin when piped)
pyrs -m package.module       # library module as a script
pyrs path/to/script.py       # source file
pyrs path/to/module.pyc      # CPython bytecode file
pyrs -c "print('hello')"     # inline source

Useful flags

pyrs --help
pyrs --version
pyrs -S path/to/script.py
pyrs --ast path/to/script.py
pyrs --bytecode path/to/script.py

REPL shortcuts

:help   :clear   :paste   :timing   :reset   :quit

Environment knobs

PYRS_CPYTHON_LIB   explicit CPython stdlib root
XDG_DATA_HOME      managed stdlib install root for the GitHub installer
PYRS_REPL_THEME    auto | dark | light
PYTHONPATH         additional import search paths
VIRTUAL_ENV        detected venv site-packages roots

Status

PYRS is an active pre-release project with CPython 3.14 parity as the correctness target.

What works today

• Broad pure-Python runtime surface (modules/packages, classes, comprehensions, generators, core async/threading flows).
• CPython bytecode execution for supported .pyc surfaces.
• Interactive REPL with multiline input, history, syntax highlighting, and command utilities.
• Large and growing stdlib support coverage.

In progress

• Long-tail CPython parity closure across stdlib/runtime edge behavior.
• Broader C-extension compatibility closure (NumPy/scientific-stack parity work).
• Additional performance and hardening milestones.

Testing

Run the local suite with nextest:

cargo nextest run

Use cargo test only when you specifically need cargo test semantics:

cargo test

Docs

• Website/docs source: website/
• Audited docs index: docs/README.md
• CPython benchmark runner: docs/CPYTHON_COMPAT_BENCHMARK.md
• Public microbench suite: docs/PUBLIC_MICROBENCHMARKS.md
• Extension capability matrix: docs/EXTENSION_CAPABILITY_MATRIX.md
• NumPy bring-up probe: docs/NUMPY_BRINGUP_GATE.md

Contributing

PRs and focused bug reports are welcome.

• For CPython parity mismatches, include a minimal reproducer and both CPython + PYRS output.
• For implementation workflow expectations in this repo, see AGENTS.md.