README.md

Small Python

Small Python is a small and embeddable Python runtime. This package, small-python, runs it from CPython: create isolated interpreters, run code in them, and give that code exactly the functions, modules, and files you choose.

Features

• Small, just a few C files, no external dependencies.
• No Python Libs. Attach your own modules.
• Almost complete Python 3.15 support.
• Run code generated by AI against only the functions you expose.
• Each runtime runs in its own worker process: an engine crash raises an exception instead of taking down your program.
• Limits on steps, memory, time, and message size.
• Can compile Python code to executables with no external dependency.
• GC uses reference counting with cycle removal.

Install

pip install small-python

Requires CPython 3.10 or newer on Linux, macOS, or Windows (x86_64).

Example

import small_python

with small_python.Runtime(step_limit=1_000_000, memory_limit=64 << 20, timeout=5) as rt:
    @rt.function
    def fetch(key, *, default=None):
        return {"answer": 42}.get(key, default)

    rt.register_module("host", {"fetch": fetch}, source="def twice(n): return n * 2")
    rt.exec("from host import twice")
    print(rt.eval("twice(fetch('answer'))"))  # 84

Documentation

• Getting started
• Embedding guide: host functions, modules, output, files, errors
• Limits and safety
• API reference
• Development: building, testing, and releasing

Build

Requires a C11 compiler. Manage the project with uv:

uv sync --locked
uv run python -c "import small_python"
uv build

See Development for tests and the release process.