Architecture

CPython is a stack-based bytecode interpreter for the Python language. A short pipeline turns source text into a code object, and a long-lived runtime executes that code object on top of an object model that all Python values share.

High-level pipeline

graph LR
    SRC[Python source] -->|Parser/lexer| TOK[Tokens]
    TOK -->|Parser/parser.c| AST[AST]
    AST -->|Python/compile.c| INSTR[Instruction sequence]
    INSTR -->|Python/flowgraph.c| CFG[Control-flow graph]
    CFG -->|Python/assemble.c| CODE[PyCodeObject]
    CODE -->|Python/ceval.c| INTERP[Adaptive interpreter]
    INTERP -.->|hot loops| TIER2[uop trace + JIT]
    TIER2 -.->|side exit / deopt| INTERP

Each arrow is implemented in a specific file:

Stage	Implementation
Tokenization	Parser/lexer/, Parser/tokenizer/
PEG parser	Parser/parser.c (generated from Grammar/python.gram)
AST	Parser/Python.asdl, Python/Python-ast.c
Symbol table	Python/symtable.c
AST → instructions	Python/compile.c, Python/codegen.c
CFG / optimizations	Python/flowgraph.c
Bytecode emission	Python/assemble.c
Adaptive interpreter	Python/ceval.c, Python/bytecodes.c
Specialization (tier 1)	Python/specialize.c
Tier 2 / JIT	Python/optimizer.c, Python/jit.c
Garbage collector	Python/gc.c, Python/gc_free_threading.c
Object allocator	Objects/obmalloc.c, Objects/mimalloc/

For every stage there is a dedicated wiki page under Systems and a longer maintainer-facing document under InternalDocs/.

Process structure

A running CPython process has three nested levels of state, all defined in Include/cpython/pystate.h:

graph TD
    RT[_PyRuntimeState — process global] --> I1[PyInterpreterState 1]
    RT --> I2[PyInterpreterState 2]
    I1 --> T1A[PyThreadState A]
    I1 --> T1B[PyThreadState B]
    I2 --> T2A[PyThreadState A]

• _PyRuntimeState — singleton, contains the GIL and global mutable state. Defined and initialized in Python/pystate.c and Python/pylifecycle.c.
• PyInterpreterState — one per subinterpreter (see PEP 684). Holds modules, builtins, the import lock, and arena pools.
• PyThreadState — one per OS thread that runs Python; holds the current frame, exception state, and recursion depth.

Python/crossinterp.c implements safe data movement between subinterpreters; Python/ceval_gil.c implements the GIL (and the per-interpreter GIL when enabled).

Object model

Every Python value — an int, a dict, a function, a class — is a pointer to a PyObject whose first words are a refcount and a type pointer. The type's PyTypeObject supplies all behaviour through C function slots (tp_call, tp_iter, tp_getattr, …). Types are themselves objects, and metaclasses (objects whose type is type) make this regular.

Built-in types live in Objects/: int is in Objects/longobject.c, str in Objects/unicodeobject.c, dict in Objects/dictobject.c, list in Objects/listobject.c, and the type type itself is in Objects/typeobject.c.

Read Object model for the layout details and inheritance rules, and Memory for how those objects are allocated.

Standard library and extension modules

The standard library is split between Python and C:

• Lib/*.py — pure-Python implementations.
• Modules/_*.c — C accelerator modules that the pure-Python module imports when available (e.g. Lib/json/__init__.py uses Modules/_json.c).
• Modules/*module.c — fully C-only stdlib modules (posix, socket, select, _io, _thread, …).

The bridge between C and Python is generated by Argument Clinic (Tools/clinic/) and the per-module */clinic/*.c.h headers. Module file layout conventions are described in Source code structure.

Build artifact graph

graph LR
    Grammar[Grammar/python.gram] --> Parser[Parser/parser.c]
    Bytecodes[Python/bytecodes.c] --> Generated[Python/generated_cases.c.h]
    Bytecodes --> Executor[Python/executor_cases.c.h]
    Bytecodes --> Optimizer[Python/optimizer_cases.c.h]
    AsdlDef[Parser/Python.asdl] --> AsdlC[Python/Python-ast.c]
    Grammar --> Tokens[Grammar/Tokens]
    Bytecodes --> JIT[jit_stencils.h]

The various code generators live in Tools/cases_generator/, Tools/peg_generator/, and Tools/jit/. These run under the regen-* Makefile targets; the generated files are checked in so an end user can build CPython without Python already installed (after the initial bootstrap).

See Tooling for details on the build system and the regeneration targets.