Pystachy

Pystachy compiles a typed subset of Python to native code through LLVM. One source file runs three ways: under CPython, under Pystachy's JIT, or as a standalone executable. Use it for CPU-bound work such as simulation, text processing and data repair.

• Executables ran 2.4 to 72 times faster than CPython across 13 benchmark programs; the Performance table below gives a sample.
• pystachy build produces an executable that needs neither Python nor LLVM. The example below builds to 138 kB on Linux x86-64.
• Source stays ordinary Python that CPython also runs, with dataclasses, generators, closures, generics and much of the standard library.
• More than 2,200 test programs must match CPython 3.13's output in both JIT and AOT modes, and more than 1,800 others must be rejected with the expected diagnostic (testing).
• The compiler is written in the subset it compiles. Each build checks that successive self-compilations emit identical LLVM IR.
• The experimental FFI calls C libraries, builds extension modules that CPython imports, and embeds CPython.

Quick start

Install the PyPI package in a Python 3.11+ virtual environment:

pip install pystachy

The installation guide covers LLVM requirements and automatic toolchain setup. Native archives and Docker images run the compiler without Python. Releases target Linux on x86-64 and ARM64, and macOS on Apple Silicon and Intel.

Save this as checkout.py. It simulates two million customers queueing for one cashier:

"""Simulate a checkout queue with one cashier and report the mean wait."""
from dataclasses import dataclass
from random import Random


@dataclass
class Stats:
    served: int = 0
    waited: float = 0.0


def arrivals(rng: Random, rate: float, count: int):
    clock = 0.0
    for _ in range(count):
        clock += rng.expovariate(rate)
        yield clock


def simulate(customers: int, seed: int) -> Stats:
    rng = Random(seed)
    stats = Stats()
    free_at = 0.0
    for arrival in arrivals(rng, 0.9, customers):
        start = max(arrival, free_at)
        free_at = start + rng.expovariate(1.0)
        stats.served += 1
        stats.waited += start - arrival
    return stats


stats = simulate(2_000_000, seed=7)
print(f"{stats.served:,} customers, mean wait {stats.waited / stats.served:.2f}")

python3 checkout.py                      # CPython reference
pystachy run checkout.py                 # Compile and run with the JIT
pystachy build checkout.py -o checkout   # Build a native executable
./checkout

All three executions print 2,000,000 customers, mean wait 9.07. The compiled random module draws the same sequence as CPython's for this seed. Annotations appear only on signatures and fields; the compiler infers local types. The getting started guide walks through a diagnostic and shows how to measure compilation and execution separately.

Performance

These are whole-process wall times for v0.4.0-alpha.3, measured on 11 November 2026: medians of five runs on one CPU of a shared 4-vCPU Intel Xeon 2.10 GHz VM, with CPython 3.13.18 and LLVM 18.1.3. JIT times include compilation, AOT times exclude the build, and every output matched CPython's. The raw samples cover the benchmarks and checkout.py.

Typed numeric loops gain the most. String and dict code gains less, and work that CPython already runs in C, such as regex matching, can be slower. Memory use can also fall: an executable that builds a list of 4,194,305 integers peaked at 34.2 MiB RSS, against 171.2 MiB under CPython. The performance guide has the full table, startup and memory costs, and reproduction commands.

How it works

Pystachy compiles the whole program before it runs, including the library modules it imports; there is no interpreter fallback. The frontend checks and infers types, specializes functions and builds a typed IR, where Pystachy's own optimizations run before LLVM's. run, build and ext share that pipeline and differ only in the last step. The compiler internals follow a program through each stage.

flowchart LR
    py["Python source<br/>and library modules"]:::source --> ir["Pystachy frontend<br/>type inference, typed IR"]:::compiler --> llvm["LLVM"]:::backend
    llvm --> run["pystachy run<br/>JIT"]:::output
    llvm --> build["pystachy build<br/>native executable"]:::output
    llvm --> ext["pystachy ext<br/>CPython extension"]:::output
    classDef source fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef compiler fill:#fef3c7,stroke:#d97706,color:#78350f
    classDef backend fill:#ede9fe,stroke:#7c3aed,color:#4c1d95
    classDef output fill:#dcfce7,stroke:#16a34a,color:#14532d

Compatibility

Pystachy is experimental and compiles a subset of Python. It rejects most unsupported constructs at compile time, naming the file and line; the known behavioral differences are listed as deviations from CPython.

An int is a checked 64-bit value: overflow raises OverflowError. A module can opt in to experimental arbitrary-precision integers or runtime-typed Any values.

Check the language guide and library support table for the features and APIs your code uses. Shipped modules include re, json, collections, itertools, functools, datetime, random, argparse and pathlib; the table gives each module's limits.

Some third-party packages compile from installed sources, and others need adaptations like the 14 maintained ports. The optional CPython bridge lets native code call packages that need CPython at runtime.

Examples

All examples lists the smaller tools, such as CSV statistics, line diffs, maze search and Monte Carlo sampling, with their checks and requirements.

Roadmap

Pystachy is focused on stronger type inference, broader library support backed by CPython comparisons, and lower compilation and execution costs.

Learn more

• Documentation covers installation, packaging, interoperability and compiler internals.
• Testing explains CPython comparisons, bootstrap checks and CI.
• Native pytest-style tests use a generated runner for a bounded fixture and parametrization subset, with CPython pytest as the oracle.
• Contributing covers development setup, focused tests and submissions.

Pystachy is MIT-licensed. See the third-party notices for licenses of adapted code.