Overview

Relevant source files

• .github/ISSUE_TEMPLATE/bug.yml
• .github/ISSUE_TEMPLATE/crash.yml
• Doc/c-api/apiabiversion.rst
• Doc/faq/general.rst
• Doc/faq/programming.rst
• Doc/glossary.rst
• Doc/library/dis.rst
• Doc/library/functions.rst
• Doc/library/stdtypes.rst
• Doc/library/string.rst
• Doc/library/string.templatelib.rst
• Doc/library/text.rst
• Doc/library/threadsafety.rst
• Doc/library/wsgiref.rst
• Doc/reference/compound_stmts.rst
• Doc/reference/datamodel.rst
• Doc/reference/expressions.rst
• Doc/reference/lexical_analysis.rst
• Doc/tutorial/classes.rst
• Doc/tutorial/inputoutput.rst
• Doc/tutorial/interpreter.rst
• Doc/tutorial/stdlib.rst
• Doc/tutorial/stdlib2.rst
• Include/internal/pycore_modsupport.h
• Include/modsupport.h
• Include/patchlevel.h
• InternalDocs/README.md
• InternalDocs/changing_grammar.md
• InternalDocs/code_objects.md
• InternalDocs/compiler.md
• InternalDocs/exception_handling.md
• InternalDocs/frames.md
• InternalDocs/garbage_collector.md
• InternalDocs/generators.md
• InternalDocs/interpreter.md
• InternalDocs/jit.md
• InternalDocs/parser.md
• Lib/test/test_builtin.py
• Objects/lnotab_notes.txt
• PC/python_ver_rc.h
• Python/bltinmodule.c
• Python/clinic/bltinmodule.c.h
• README.rst

Purpose and Scope

CPython is the reference implementation of the Python programming language, written in C. This document provides an architectural overview of CPython's core systems for Python 3.14 (released October 2025) and 3.15 (in development).

Major architectural components:

• Compilation Pipeline: Transformation of Python source code into bytecode via AST generation, symbol table construction, control flow graph optimization, and bytecode assembly.
• Execution Systems: Three-tier execution model with bytecode interpreter (Tier 1), adaptive specialization, trace optimizer (Tier 2), and optional JIT compilation to native machine code.
• Object System: PyObject-based type hierarchy with PyTypeObject metaclass, reference counting, and cyclic garbage collection.
• Runtime Management: Hierarchical state structures (_PyRuntimeState → PyInterpreterState → PyThreadState), Global Interpreter Lock (GIL) implementation, and multi-interpreter support.
• Build System: Autoconf-based configuration, platform-specific builds, and CI/CD infrastructure with GitHub Actions.

Navigation to detailed subsystems:

• Code compilation: Code Compilation Pipeline
• Execution architecture: Code Execution Systems
• Object model and memory: Object System and Memory Management
• Runtime infrastructure: Runtime Infrastructure
• Standard library: Standard Library - Core Modules
• Build and development: Build System and Development Infrastructure

Sources: Include/patchlevel.h23-30 InternalDocs/README.md1-66 Doc/reference/datamodel.rst1-120

CPython Architecture: Major Components

Diagram: CPython Architecture - Data Flow and Key Code Symbols

This diagram maps the flow of Python code through CPython's major subsystems, annotated with actual function names, file paths, and data structures from the codebase.

Sources: InternalDocs/README.md17-66 Doc/reference/lexical_analysis.rst10-23 Doc/reference/datamodel.rst9-65 Doc/library/dis.rst17-43

Bytecode Definition and Generation System

CPython's bytecode system is defined in a single source of truth: Python/bytecodes.c. This file uses a DSL to define instructions, which are then processed by Python-based generators to produce the C code used by the interpreter and optimizer.

Diagram: Bytecode DSL to Generated Code Pipeline

Instruction Definition Macros:

Macro	Purpose
inst(name, stack_effect)	Defines a Tier 1 bytecode instruction.
op(name, stack_effect)	Defines a Micro-operation (UOp) for the Tier 2 optimizer.
macro(name)	Combines multiple micro-ops into a single Tier 1 instruction.
family(name, ...)	Defines a specialization family for adaptive bytecode.

Sources: InternalDocs/README.md31-40 Doc/library/dis.rst38-44 Python/bltinmodule.c7-8

Execution Model: Three-Tier Architecture

CPython implements a multi-tier execution strategy to balance fast startup with high-performance steady-state execution.

Tier 1: Bytecode Interpreter

The core evaluation loop is _PyEval_EvalFrameDefault in Python/ceval.c. It processes standard bytecode instructions. This tier includes Adaptive Specialization, where instructions like LOAD_ATTR are "quickened" into specialized forms (e.g., LOAD_ATTR_INSTANCE_VALUE) after observing specific types at runtime.

Tier 2: Trace Optimizer

When a loop becomes "hot" (monitored by JUMP_BACKWARD counters), the Tier 2 optimizer (Python/optimizer.c) translates the bytecode into a trace of micro-operations (UOps). These UOps are simpler than bytecode and allow for more aggressive optimizations like guard elimination and constant propagation.

JIT Compilation

If enabled, the JIT compiler (Python/jit.c) transforms Tier 2 UOp traces into native machine code using a "copy-and-patch" technique. This avoids the overhead of the interpreter dispatch loop for hot code paths.

Sources: InternalDocs/README.md40-44 Doc/library/dis.rst33-53 Python/bltinmodule.c102-106

Object System and Data Model

All data in CPython is represented as objects. Every object has an identity, a type, and a value.

• Identity: Represented by the memory address of the object; retrieved via id().
• Type: Determines supported operations (e.g., len()); retrieved via type().
• Value: The data stored in the object. Objects are mutable (value can change, like list) or immutable (value is fixed, like int or str).

Built-in Types

The interpreter includes several fundamental built-in types:

• Numerics: int, float, complex.
• Sequences: list, tuple, range, str, bytes.
• Mappings: dict.
• Sets: set, frozenset.
• Constants: None, True, False, NotImplemented, Ellipsis (...).

Sources: Doc/reference/datamodel.rst9-55 Doc/library/stdtypes.rst10-26 Doc/library/functions.rst7-41 Doc/reference/expressions.rst79-87

Runtime Infrastructure

The CPython runtime manages the lifecycle of the interpreter and its threads.

• _PyRuntimeState: Global state for the entire process.
• PyInterpreterState: State for an individual Python interpreter. CPython supports multiple interpreters within a single process.
• PyThreadState: State for an individual thread of execution, including the current frame stack and exception information.
• Garbage Collection: Primarily uses Reference Counting for immediate cleanup, supplemented by a Generational Cyclic GC to detect and reclaim objects in circular references.

Sources: Doc/glossary.rst145-154 Doc/reference/datamodel.rst57-74 Python/bltinmodule.c204-207 InternalDocs/README.md46-52

Standard Library and Built-in Functions

CPython provides a rich set of built-in functions and a comprehensive standard library.

Built-in Functions

Functions like abs(), len(), print(), and __import__() are always available and implemented in C for performance. For example, __build_class__ handles the logic for creating new class objects at runtime.

Standard Library

The library spans from core system interfaces to high-level data formats:

• OS Interface: os, io, pathlib.
• Concurrency: threading, asyncio, multiprocessing.
• Data Formats: json, pickle, csv.
• Development: unittest, dis, pdb.

Sources: Doc/library/functions.rst10-41 Python/bltinmodule.c101-135 Doc/library/stdtypes.rst1-17 Doc/glossary.rst28-39