# pypy/pypy architecture

> Architecture diagram of the GitHub repository pypy/pypy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pypy/pypy
- Repository: https://github.com/pypy/pypy

## Overview

PyPy is a Python-language interpreter implemented in Python and built on the RPython compiler framework. The primary runtime path starts in the interpreter entry module and creates the standard object space used to execute Python. The repository also includes RPython’s annotation, low-level representation, and JIT backend layers, plus a broad Python 2.7 standard-library implementation. The graph reflects documented product scope and indexed imports; source excerpts are partial, so connections between unsampled compiler stages are omitted.

Main entry points: [`pypy/interpreter/main.py`](https://github.com/pypy/pypy/blob/main/pypy/interpreter/main.py) (Interpreter Entry), [`rpython/annotator/model.py`](https://github.com/pypy/pypy/blob/main/rpython/annotator/model.py) (Type Annotation), [`rpython/rtyper/lltypesystem/lltype.py`](https://github.com/pypy/pypy/blob/main/rpython/rtyper/lltypesystem/lltype.py) (Low-Level Types), [`rpython/rlib/rawstorage.py`](https://github.com/pypy/pypy/blob/main/rpython/rlib/rawstorage.py) (Raw Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Python Runtime"]
  node_entry["Interpreter Entry<br/>[main.py]"]
  node_eval["Interpreter Evaluation<br/>[eval.py]"]
  node_module["Module Handling<br/>[module.py]"]
  node_errors["Interpreter Errors<br/>[error.py]"]
  node_objspace["Standard Object Space<br/>[objspace.py]"]
  node_callmethod["Method Calls<br/>[callmethod.py]"]
  node_sysapp["Sys Services<br/>[app.py]"]
end

subgraph group_stdlib["Python Library"]
  node_future["Future Features<br/>[__future__.py]"]
  node_os["OS Interface<br/>[os.py]"]
  node_collections["Container Types<br/>[collections.py]"]
  node_threading["Threading<br/>[threading.py]"]
end

subgraph group_rpython["RPython Framework"]
  node_annotator["Type Annotation<br/>[model.py]"]
  node_objectmodel["RPython Object Model<br/>[objectmodel.py]"]
  node_types["Annotation Helpers<br/>[types.py]"]
  node_controller["Controller Typing<br/>[controllerentry.py]"]
  node_lowtypes["Low-Level Types<br/>[lltype.py]"]
  node_memory["Memory Layout<br/>[llmemory.py]"]
  node_rawstorage["Raw Storage<br/>[rawstorage.py]"]
  node_flowspace["Flow Analysis<br/>[flowcontext.py]"]
  node_translator["C Translation<br/>[database.py]"]
end

subgraph group_jit["JIT Runtime"]
  node_jitbackend["JIT Backend<br/>[llmodel.py]"]
  node_jitlogs["JIT Log Tools<br/>[storage.py]"]
end

node_user(("Python User"))

node_user -->|"runs Python"| node_entry
node_entry -->|"uses evaluation"| node_eval
node_entry -->|"uses modules"| node_module
node_entry -->|"uses errors"| node_errors
node_entry -->|"creates space"| node_objspace
node_entry -->|"uses sys"| node_sysapp
node_callmethod -->|"uses types"| node_objspace
node_annotator -->|"uses annotations"| node_types
node_objectmodel -->|"uses annotations"| node_annotator
node_objectmodel -->|"uses types"| node_lowtypes
node_controller -->|"defines annotations"| node_annotator
node_controller -->|"uses specialization"| node_objectmodel
node_memory -->|"uses types"| node_lowtypes
node_rawstorage -->|"allocates storage"| node_lowtypes
node_rawstorage -->|"uses memory"| node_memory
node_rawstorage -->|"defines annotations"| node_annotator
node_jitbackend -->|"uses types"| node_lowtypes
node_jitbackend -->|"uses memory"| node_memory

click node_entry "https://github.com/pypy/pypy/blob/main/pypy/interpreter/main.py"
click node_eval "https://github.com/pypy/pypy/blob/main/pypy/interpreter/eval.py"
click node_module "https://github.com/pypy/pypy/blob/main/pypy/interpreter/module.py"
click node_errors "https://github.com/pypy/pypy/blob/main/pypy/interpreter/error.py"
click node_objspace "https://github.com/pypy/pypy/blob/main/pypy/objspace/std/objspace.py"
click node_callmethod "https://github.com/pypy/pypy/blob/main/pypy/objspace/std/callmethod.py"
click node_sysapp "https://github.com/pypy/pypy/blob/main/pypy/module/sys/app.py"
click node_future "https://github.com/pypy/pypy/blob/main/lib-python/2.7/__future__.py"
click node_os "https://github.com/pypy/pypy/blob/main/lib-python/2.7/os.py"
click node_collections "https://github.com/pypy/pypy/blob/main/lib-python/2.7/collections.py"
click node_threading "https://github.com/pypy/pypy/blob/main/lib-python/2.7/threading.py"
click node_annotator "https://github.com/pypy/pypy/blob/main/rpython/annotator/model.py"
click node_objectmodel "https://github.com/pypy/pypy/blob/main/rpython/rlib/objectmodel.py"
click node_types "https://github.com/pypy/pypy/blob/main/rpython/rlib/types.py"
click node_controller "https://github.com/pypy/pypy/blob/main/rpython/rtyper/controllerentry.py"
click node_lowtypes "https://github.com/pypy/pypy/blob/main/rpython/rtyper/lltypesystem/lltype.py"
click node_memory "https://github.com/pypy/pypy/blob/main/rpython/rtyper/lltypesystem/llmemory.py"
click node_rawstorage "https://github.com/pypy/pypy/blob/main/rpython/rlib/rawstorage.py"
click node_flowspace "https://github.com/pypy/pypy/blob/main/rpython/flowspace/flowcontext.py"
click node_translator "https://github.com/pypy/pypy/blob/main/rpython/translator/c/database.py"
click node_jitbackend "https://github.com/pypy/pypy/blob/main/rpython/jit/backend/llsupport/llmodel.py"
click node_jitlogs "https://github.com/pypy/pypy/blob/main/rpython/tool/jitlogparser/storage.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_eval,node_module,node_errors,node_objspace,node_callmethod,node_sysapp,node_user toneBlue
class node_future,node_os,node_collections,node_threading toneAmber
class node_annotator,node_objectmodel,node_types,node_controller,node_lowtypes,node_memory,node_rawstorage,node_flowspace,node_translator toneMint
class node_jitbackend,node_jitlogs toneRose
```

## Components

### Python Runtime

- [Interpreter Entry](https://github.com/pypy/pypy/blob/main/pypy/interpreter/main.py): `pypy/interpreter/main.py`
- [Interpreter Evaluation](https://github.com/pypy/pypy/blob/main/pypy/interpreter/eval.py): `pypy/interpreter/eval.py`
- [Module Handling](https://github.com/pypy/pypy/blob/main/pypy/interpreter/module.py): `pypy/interpreter/module.py`
- [Interpreter Errors](https://github.com/pypy/pypy/blob/main/pypy/interpreter/error.py): `pypy/interpreter/error.py`
- [Standard Object Space](https://github.com/pypy/pypy/blob/main/pypy/objspace/std/objspace.py): `pypy/objspace/std/objspace.py`
- [Method Calls](https://github.com/pypy/pypy/blob/main/pypy/objspace/std/callmethod.py): `pypy/objspace/std/callmethod.py`
- [Sys Services](https://github.com/pypy/pypy/blob/main/pypy/module/sys/app.py): `pypy/module/sys/app.py`

### Python Library

- [Future Features](https://github.com/pypy/pypy/blob/main/lib-python/2.7/__future__.py): `lib-python/2.7/__future__.py`
- [OS Interface](https://github.com/pypy/pypy/blob/main/lib-python/2.7/os.py): `lib-python/2.7/os.py`
- [Container Types](https://github.com/pypy/pypy/blob/main/lib-python/2.7/collections.py): `lib-python/2.7/collections.py`
- [Threading](https://github.com/pypy/pypy/blob/main/lib-python/2.7/threading.py): `lib-python/2.7/threading.py`

### RPython Framework

- [Type Annotation](https://github.com/pypy/pypy/blob/main/rpython/annotator/model.py): `rpython/annotator/model.py`
- [RPython Object Model](https://github.com/pypy/pypy/blob/main/rpython/rlib/objectmodel.py): `rpython/rlib/objectmodel.py`
- [Annotation Helpers](https://github.com/pypy/pypy/blob/main/rpython/rlib/types.py): `rpython/rlib/types.py`
- [Controller Typing](https://github.com/pypy/pypy/blob/main/rpython/rtyper/controllerentry.py): `rpython/rtyper/controllerentry.py`
- [Low-Level Types](https://github.com/pypy/pypy/blob/main/rpython/rtyper/lltypesystem/lltype.py): `rpython/rtyper/lltypesystem/lltype.py`
- [Memory Layout](https://github.com/pypy/pypy/blob/main/rpython/rtyper/lltypesystem/llmemory.py): `rpython/rtyper/lltypesystem/llmemory.py`
- [Raw Storage](https://github.com/pypy/pypy/blob/main/rpython/rlib/rawstorage.py): `rpython/rlib/rawstorage.py`
- [Flow Analysis](https://github.com/pypy/pypy/blob/main/rpython/flowspace/flowcontext.py): `rpython/flowspace/flowcontext.py`
- [C Translation](https://github.com/pypy/pypy/blob/main/rpython/translator/c/database.py): `rpython/translator/c/database.py`

### JIT Runtime

- [JIT Backend](https://github.com/pypy/pypy/blob/main/rpython/jit/backend/llsupport/llmodel.py): `rpython/jit/backend/llsupport/llmodel.py`
- [JIT Log Tools](https://github.com/pypy/pypy/blob/main/rpython/tool/jitlogparser/storage.py): `rpython/tool/jitlogparser/storage.py`

### Other components

- **Python User**

## Connections

- Python User → Interpreter Entry: runs Python
- Interpreter Entry → Interpreter Evaluation: uses evaluation (evidence: `pypy/interpreter/main.py`)
- Interpreter Entry → Module Handling: uses modules (evidence: `pypy/interpreter/main.py`)
- Interpreter Entry → Interpreter Errors: uses errors (evidence: `pypy/interpreter/main.py`)
- Interpreter Entry → Standard Object Space: creates space (evidence: `pypy/interpreter/main.py`)
- Interpreter Entry → Sys Services: uses sys (evidence: `pypy/interpreter/main.py`)
- Method Calls → Standard Object Space: uses types (evidence: `pypy/objspace/std/callmethod.py`)
- Type Annotation → Annotation Helpers: uses annotations (evidence: `rpython/rlib/types.py`)
- RPython Object Model → Type Annotation: uses annotations (evidence: `rpython/rlib/objectmodel.py`)
- RPython Object Model → Low-Level Types: uses types (evidence: `rpython/rlib/objectmodel.py`)
- Controller Typing → Type Annotation: defines annotations (evidence: `rpython/rtyper/controllerentry.py`)
- Controller Typing → RPython Object Model: uses specialization (evidence: `rpython/rtyper/controllerentry.py`)
- Memory Layout → Low-Level Types: uses types (evidence: `rpython/rtyper/lltypesystem/llmemory.py`)
- Raw Storage → Low-Level Types: allocates storage (evidence: `rpython/rlib/rawstorage.py`)
- Raw Storage → Memory Layout: uses memory (evidence: `rpython/rlib/rawstorage.py`)
- Raw Storage → Type Annotation: defines annotations (evidence: `rpython/rlib/rawstorage.py`)
- JIT Backend → Low-Level Types: uses types (evidence: `rpython/jit/backend/llsupport/llmodel.py`)
- JIT Backend → Memory Layout: uses memory (evidence: `rpython/jit/backend/llsupport/llmodel.py`)