Pystachy

Pystachy compiles a typed subset of Python to native code through LLVM. Use it for CPU-bound work such as text processing, data repair, and simulation while keeping your code in Python. The compiler is self-hosting, and its JIT and AOT modes share the same typed intermediate representation.

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 are also available.

Then save this as demo.py:

from fnmatch import fnmatchcase
from functools import lru_cache


@lru_cache(maxsize=256)
def classify(name: str) -> str:
    return "api" if fnmatchcase(name, "api.*") else "other"


print(classify("api.request"), classify("worker.done"))

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

All three executions print api other. The executable runs without Python. The getting started guide walks through a diagnostic and shows how to measure compilation and execution separately.

What you can build

Browse all examples for their purposes, checks and requirements. See the performance guide for measured workloads, startup and memory costs, and reproduction commands. On supported Linux native installs, run automatically reuses unchanged programs. PYSTACHY_PROGRAM_CACHE=0 forces compilation; build produces a standalone executable.

Compatibility

Pystachy is experimental. It supports typed containers, classes, generators and other common Python constructs. General multiple inheritance, async and match are outside the supported subset. Integers are checked 64-bit values by default. Promoting integers and dynamic Any are opt-in. Prefer concrete types, generics and closed unions; reserve dynamic storage for open interface boundaries. Dynamic Any includes a bounded prototype for class values, type-keyed registries, generic calls and annotated factories.

Check the language guide and library support table for the features and APIs your code uses. The library includes bounded argparse, enum and experimental static ctypes declarations. Some packages compile from installed sources, and others need adaptations like the maintained ports. The optional CPython bridge lets native code call packages that need CPython at runtime.

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.
• Contributing covers development setup, focused tests and submissions.

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