Overview

Relevant source files

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 code
Object System: PyObject-based type hierarchy with PyTypeObject metaclass, reference counting, and cyclic garbage collection
Runtime Management: Hierarchical state structures (_PyRuntimeState → PyInterpreterState → PyThreadState), GIL implementation, and multi-interpreter support
Build System: Autoconf-based configuration, platform-specific builds, 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: Doc/whatsnew/3.14.rst1-100 Python/bytecodes.c1-150 Python/ceval.c Python/optimizer.c1-100 Objects/typeobject.c1-100

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. Each box represents concrete code entities that can be located in the source tree.

Sources: Python/bytecodes.c1-147 Python/ceval.c Python/compile.c Python/optimizer.c1-200 Python/generated_cases.c.h1-100 Python/executor_cases.c.h1-100 Python/optimizer_cases.c.h1-100 Objects/typeobject.c1-100 Python/pystate.c1-150 Include/object.h Python/jit.c

Bytecode Definition and Generation System

Python/bytecodes.c is the single source of truth for all bytecode instructions in CPython. It uses a domain-specific language (DSL) with macros to define instructions, which are then processed by code generators to produce multiple output files.

Diagram: Bytecode DSL to Generated Code Pipeline

Instruction Definition Macros:

Macro	Purpose	Example
`inst(name, stack_effect)`	Tier 1 bytecode instruction	`inst(LOAD_FAST, (-- value))`
`op(name, stack_effect)`	Micro-operation (UOp) for Tier 2	`op(_GUARD_TOS_INT, (value -- value))`
`macro(name)`	Combines multiple ops	`macro(STORE_FAST) = _SWAP_FAST + POP_TOP;`
`family(name, ...)`	Specialization family	`family(TO_BOOL, ...) = { TO_BOOL_BOOL, ... };`
`replicate(N)`	Generate N copies with suffixes	`replicate(8) inst(LOAD_FAST, ...)`

Code Generation Process:

Tools/cases_generator/ parsers read Python/bytecodes.c1-147
Each generator extracts relevant information and applies transformations
Output files are generated with C code implementing the instructions
Main CPython build includes these generated files

Sources: Python/bytecodes.c1-147 Python/generated_cases.c.h1-100 Python/executor_cases.c.h1-100 Python/optimizer_cases.c.h1-100 Include/internal/pycore_opcode_metadata.h1-50 Include/internal/pycore_uop_ids.h1-50 Include/internal/pycore_uop_metadata.h1-50

Execution Model: Three-Tier Architecture

CPython uses a three-tier execution model to balance performance and compatibility:

Tier	Description	Implementation	When Used
Tier 1	Traditional bytecode interpreter	Python/generated_cases.c.h included in Python/ceval.c	All code initially, cold code
Tier 2	Optimized UOp traces	Python/executor_cases.c.h with Python/optimizer.c	Hot loops after ~128 iterations
JIT	Native machine code	Python/jit.c with Tools/jit/ stencils	Tier 2 traces when JIT enabled

Tier 1: Bytecode Interpreter

The core evaluation loop is _PyEval_EvalFrameDefault() in Python/ceval.c1-30 It executes bytecode instructions generated from Python/bytecodes.c using a switch-based dispatch mechanism.

Diagram: Tier 1 Bytecode Interpreter Execution Flow

Key data structures:

_PyInterpreterFrame: Current frame being executed Include/internal/pycore_interpframe.h
PyCodeObject: Contains bytecode and metadata Include/cpython/code.h
_PyStackRef: Stack reference wrapper for values Include/internal/pycore_stackref.h

Sources: Python/ceval.c1-30 Python/generated_cases.c.h1-100 Python/specialize.c Include/internal/pycore_interpframe.h

Tier 2: Optimizer and UOp Traces

When a JUMP_BACKWARD instruction executes frequently (default: JUMP_BACKWARD_INITIAL_VALUE = 128), the optimizer converts the hot loop into a Tier 2 trace of micro-operations (UOps).

Diagram: Tier 2 Optimizer - Function Names and Data Structures

Optimization Techniques:

Technique	Implementation	File
Symbolic execution	`op(_LOAD_FAST)`, `op(_GUARD_TOS_INT)` in DSL	Python/optimizer_bytecodes.c90-600
Type tracking	`JitOptSymbol` with type, const, null info	Python/optimizer_analysis.c
Guard elimination	`optimize_to_bool`, `eliminate_pop_guard`	Python/optimizer_analysis.c
Constant folding	Evaluate ops on `sym_is_const` values	Python/optimizer_bytecodes.c
Copy propagation	Track value flow in `frame->locals`	Python/optimizer_analysis.c

Key Data Structures:

Sources: Python/optimizer.c80-600 Python/optimizer_analysis.c1-800 Python/optimizer_bytecodes.c1-700 Include/internal/pycore_optimizer.h1-150 Include/internal/pycore_backoff.h

JIT Compilation

When JIT is enabled (via --enable-experimental-jit build flag), Tier 2 traces are compiled to native machine code.

Diagram: JIT Compilation Process

The JIT uses a copy-and-patch approach:

Pre-compiled machine code "stencils" are generated at build time for each UOp Tools/jit/
At runtime, stencils are copied and patched with actual operands, addresses, and jump targets
The result is a native function stored in executable memory

JIT structures:

_Py_CODEUNIT *jit_code: Pointer to native code in _PyExecutorObject
Stencils: Generated by LLVM compiler via Tools/jit/_stencils.py

Sources: Python/jit.c1-100 Tools/jit/_targets.py1-50 Tools/jit/_stencils.py

Object System and Type Hierarchy

All Python objects derive from PyObject, defined in Include/object.h The type system is built on PyTypeObject defined in Objects/typeobject.c

Diagram: Object Type Hierarchy

PyObject Structure

Every Python object starts with the PyObject header:

Include/object.h defines this base structure along with reference counting macros:

Py_INCREF(op): Increment reference count
Py_DECREF(op): Decrement and potentially deallocate
Py_XINCREF(op), Py_XDECREF(op): NULL-safe versions

Sources: Include/object.h Objects/object.c1-100 Objects/typeobject.c1-100

Memory Management

CPython uses a multi-layered memory management system:

Diagram: Memory Management Layers

Reference Counting

The primary memory management mechanism is reference counting:

Every object has ob_refcnt tracking how many references exist
When count reaches 0, tp_dealloc is called
Simple and deterministic, but cannot handle reference cycles

Objects/object.c1-100 implements core reference counting functions.

Garbage Collection

The cyclic garbage collector handles reference cycles:

Tracks container objects (lists, dicts, etc.) via PyGC_Head
Uses generational collection with 3 generations (young, old, permanent)
Periodically runs cycle detection algorithm

Implementations:

GIL build: Python/gc.c1-100
Free-threading build: Python/gc_free_threading.c1-100 with stop-the-world pauses

Free-Threading Considerations

In free-threaded builds (Py_GIL_DISABLED):

Biased reference counting: Separate shared and local reference counts
Immortal objects: Special refcount value prevents deallocation
Stop-the-world GC: All threads pause during collection
Thread-local allocators: mimalloc reduces contention

Sources: Objects/object.c1-200 Python/gc.c1-50 Python/gc_free_threading.c1-50 Include/internal/pycore_object.h1-100

Runtime State Management

CPython's runtime state is organized hierarchically:

Diagram: Runtime State Hierarchy

Key State Structures

Structure	Scope	Key Fields	File
`_PyRuntimeState`	Process-wide	`interpreters`, `gilstate`, `gc`	Include/internal/pycore_runtime.h
`PyInterpreterState`	Per-interpreter	`modules`, `builtins`, `ceval`, `gc`	Include/internal/pycore_interp.h
`PyThreadState`	Per-thread	`interp`, `frame`, `recursion_limit`, `curexc_*`	Include/cpython/pystate.h
`_PyInterpreterFrame`	Per-call	`f_code`, `f_locals`, `prev`, `stacktop`	Include/internal/pycore_interpframe.h

Thread State Access

Current thread state is accessed via thread-local storage:

_Py_tss_tstate: TLS variable in Python/pystate.c73
_PyThreadState_GET(): Fast macro to get current thread state
PyGILState_Ensure(): Acquire GIL and get thread state

The GIL (Global Interpreter Lock) is managed through:

_PyEval_AcquireLock(): Acquire GIL
_PyEval_ReleaseLock(): Release GIL
drop_gil(), take_gil(): Core GIL operations

Sources: Python/pystate.c1-150 Include/internal/pycore_runtime.h Include/internal/pycore_interp.h Python/ceval.c

Initialization and Shutdown

CPython's initialization follows a carefully orchestrated sequence:

Diagram: Initialization and Shutdown Sequence

Key initialization functions:

Py_InitializeFromConfig(): Main entry point Python/pylifecycle.c
_PyRuntime_Initialize(): Initialize global runtime state Python/pystate.c
pycore_init_types(): Initialize built-in types Python/pylifecycle.c
_PyImport_Init(): Initialize import machinery Python/import.c

Sources: Modules/main.c Python/initconfig.c1-50 Python/pylifecycle.c1-100 Python/pystate.c1-100

Performance Optimizations

CPython employs several optimization strategies:

1. Adaptive Specialization

Bytecode instructions can be specialized based on observed types at runtime:

Counter in inline cache tracks execution frequency
After threshold, _Py_Specialize_*() functions replace generic opcodes with specialized versions
Examples: LOAD_ATTR → LOAD_ATTR_INSTANCE_VALUE, BINARY_OP → BINARY_OP_ADD_INT

Implementation: Python/specialize.c

2. Inline Caching

Specialized instructions use inline cache entries to store:

Type version numbers
Attribute offsets
Function pointers
Dictionary key indices

Cache entries follow the instruction in bytecode: opcode.h cache definitions

3. Tier 2 Optimizer Techniques

The optimizer applies several transformations:

Guard elimination: Remove redundant type checks
Constant folding: Evaluate constant expressions
Copy propagation: Track value flow
Dead code elimination: Remove unused computations
Function inlining: Inline short functions into trace

Implementation: Python/optimizer_analysis.c Python/optimizer_bytecodes.c

4. Object Freelists

Frequently allocated types maintain freelists to avoid malloc/free overhead:

Float, int, list, dict, frame objects have dedicated freelists
Deallocated objects return to freelist instead of being freed
Reduces memory allocator pressure

Implementation: Include/internal/pycore_freelist.h Objects/object.c

Sources: Python/specialize.c1-50 Python/optimizer_analysis.c1-100 Include/internal/pycore_freelist.h

Key Configuration Options

CPython behavior is configured through build-time options, runtime configuration, and command-line flags.

Build-Time Configuration

Configure Option	Effect	Implementation Files
`--enable-optimizations`	Profile-guided optimization (PGO)	configure.ac3847-3900 Makefile.pre.in
`--enable-experimental-jit`	JIT compiler with copy-and-patch	configure.ac Python/jit.c Tools/jit/
`--disable-gil`	Free-threaded mode (Py_GIL_DISABLED)	configure.ac impacts all C code
`--with-tail-call-interp`	Tail-call interpreter (Clang 19+)	configure.ac Python/ceval.c
`--with-pydebug`	Debug build with `Py_DEBUG`	configure.ac enables assertions
`--with-trace-refs`	Track all object allocations	configure.ac Include/object.h
`--with-valgrind`	Valgrind compatibility	configure.ac

Runtime Configuration Structure

Include/cpython/initconfig.h defines PyConfig with fields for:

optimization_level: 0, 1 (-O), or 2 (-OO)
bytes_warning: Warn on bytes/str comparisons
inspect: Enter interactive mode after script
isolated: Isolated mode (ignore environment variables)
use_environment: Use PYTHON* environment variables
dev_mode: Development mode (-X dev)

Configuration flow: PyConfig_Read() → Py_InitializeFromConfig() in Python/initconfig.c

Command-Line Options

Option	Effect	PyConfig Field
`-O`	`__debug__` = False, remove asserts	`optimization_level = 1`
`-OO`	Also remove docstrings	`optimization_level = 2`
`-X dev`	Development mode, extra warnings	`dev_mode = 1`
`-X gil=0`	Disable GIL (free-threaded builds only)	Runtime check
`-X importtime`	Show import time breakdown	Flag check in import code
`-X int_max_str_digits=N`	Limit int string conversion	`int_max_str_digits`

Environment Variables:

PYTHONPATH: Prepend to sys.path
PYTHONHOME: Override standard library location
PYTHONOPTIMIZE: Same as -O
PYTHONDONTWRITEBYTECODE: Don't write .pyc files
PYTHON_GIL=0: Disable GIL at runtime (Python 3.13+)
PYTHON_UOPS_OPTIMIZE=0: Disable Tier 2 optimizer

Sources: Python/initconfig.c1-200 configure.ac1-100 Include/cpython/initconfig.h Doc/using/configure.rst1-100

Testing and Debugging

CPython includes extensive testing infrastructure:

Test Suite

Unit tests: Lib/test/ directory
C API tests: Lib/test/test_capi/
Tier 2 tests: Lib/test/test_capi/test_opt.py1-100
GC tests: Lib/test/test_gc.py1-50

Debug Tools

Tool	Purpose	Usage
`sys._debugmallocstats()`	Memory allocation stats	Call from Python
`_opcode.get_executor()`	Inspect Tier 2 executors	Lib/test/test_capi/test_opt.py33-42
`PYTHONUOPS_OPTIMIZE=0`	Disable Tier 2 optimizer	Environment variable
`-X dev`	Development mode with warnings	Command-line flag

Tracing

Tier 2 compilation can be traced with:

PYTHON_OPT_DEBUG=1: Print optimization decisions
Trace inspection via _opcode module

Sources: Lib/test/test_capi/test_opt.py1-200 Lib/test/test_gc.py1-100 Python/optimizer.c