Overview

Relevant source files

• Doc/c-api/object.rst
• Doc/c-api/refcounting.rst
• Doc/library/gc.rst
• Include/cpython/object.h
• Include/cpython/pystate.h
• Include/internal/pycore_ceval.h
• Include/internal/pycore_debug_offsets.h
• Include/internal/pycore_freelist_state.h
• Include/internal/pycore_gc.h
• Include/internal/pycore_interp.h
• Include/internal/pycore_interp_structs.h
• Include/internal/pycore_jit.h
• Include/internal/pycore_object.h
• Include/internal/pycore_opcode_metadata.h
• Include/internal/pycore_optimizer.h
• Include/internal/pycore_optimizer_types.h
• Include/internal/pycore_pystate.h
• Include/internal/pycore_tstate.h
• Include/internal/pycore_typeobject.h
• Include/internal/pycore_uop_ids.h
• Include/internal/pycore_uop_metadata.h
• Lib/test/test_capi/test_object.py
• Lib/test/test_capi/test_opt.py
• Lib/test/test_frame_pointer_unwind.py
• Lib/test/test_gc.py
• Lib/test/test_range.py
• Modules/_testcapi/object.c
• Modules/clinic/gcmodule.c.h
• Modules/gcmodule.c
• Objects/classobject.c
• Objects/clinic/rangeobject.c.h
• Objects/methodobject.c
• Objects/object.c
• Objects/rangeobject.c
• Objects/structseq.c
• Objects/typeobject.c
• Python/bytecodes.c
• Python/ceval.c
• Python/ceval_macros.h
• Python/executor_cases.c.h
• Python/gc.c
• Python/gc_free_threading.c
• Python/generated_cases.c.h
• Python/jit.c
• Python/optimizer.c
• Python/optimizer_analysis.c
• Python/optimizer_bytecodes.c
• Python/optimizer_cases.c.h
• Python/optimizer_symbols.c
• Python/pylifecycle.c
• Python/pystate.c
• Tools/jit/_optimizers.py
• Tools/jit/_schema.py
• Tools/jit/_stencils.py
• Tools/jit/_targets.py
• Tools/jit/_writer.py
• Tools/jit/jit.h
• Tools/jit/shim.c
• Tools/jit/template.c

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, covering:

• Compilation Pipeline: How Python source code is transformed into bytecode through AST generation, symbol table construction, and assembly
• Execution Systems: The three-tier execution model including the bytecode interpreter, optimizer (Tier 2), and JIT compiler
• Object System: The type hierarchy, reference counting, and memory management infrastructure
• Runtime Management: Interpreter state, thread management, and the Global Interpreter Lock (GIL)

For specific subsystems, see:

• Code compilation details: Code Compilation Pipeline
• Execution system internals: Code Execution Systems
• Object and memory management: Object System and Memory Management
• Runtime state management: Runtime Infrastructure
• Standard library modules: Standard Library - Core Modules
• Build system details: Build System and Development Infrastructure

Sources: Python/bytecodes.c1-100 Python/ceval.c1-50 Python/optimizer.c1-50 Objects/typeobject.c1-50

CPython Architecture: Major Components

Diagram: CPython Architecture and Data Flow

This diagram shows how Python code flows through the system, from source to execution, and the key C structures and files involved.

Sources: Python/bytecodes.c1-10 Python/ceval.c1-30 Python/optimizer.c115-150 Python/compile.c Objects/typeobject.c1-40 Python/pystate.c1-50

Bytecode Definition and Generation System

The heart of CPython's execution model is Python/bytecodes.c which serves as the single source of truth for all bytecode instructions. This file uses a domain-specific language with macros like inst(), op(), and macro() to define instructions.

Diagram: Bytecode Definition and Code Generation Pipeline

The Python/bytecodes.c1-147 file contains instruction definitions using special macros:

• inst(name, ...): Defines a tier 1 instruction
• op(name, ...): Defines a micro-operation (UOp)
• macro(name): Defines a macro instruction composed of multiple ops
• family(name, ...): Defines a specialization family

Code generators in Tools/cases_generator/ process this file to produce execution handlers, metadata, and optimization rules.

Sources: Python/bytecodes.c1-147 Python/generated_cases.c.h1-20 Python/executor_cases.c.h1-20 Python/optimizer_cases.c.h1-20

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 is executed frequently (default threshold: 128 times), CPython may optimize it into a Tier 2 executor.

Diagram: Tier 2 Optimization Pipeline

The optimizer performs several key analyses:

• Symbolic execution: Tracks symbolic values through Python/optimizer_bytecodes.c
• Type inference: Records and propagates type information
• Guard elimination: Removes redundant type/value checks
• Constant folding: Evaluates constant expressions at compile time

Key structures:

• _PyExecutorObject: Represents a compiled trace Include/internal/pycore_optimizer.h
• _PyUOpInstruction: Micro-operation with opcode, oparg, and operands Include/internal/pycore_uop.h
• JitOptContext: Optimization context with symbol tables Python/optimizer_analysis.c

Sources: Python/optimizer.c115-200 Python/optimizer_analysis.c1-100 Python/optimizer_bytecodes.c1-100 Include/internal/pycore_optimizer.h1-50

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:

1. Pre-compiled machine code "stencils" are generated at build time for each UOp Tools/jit/
2. At runtime, stencils are copied and patched with actual operands, addresses, and jump targets
3. 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 can be configured through several mechanisms:

Build-Time Configuration

Option	Effect	Files
--enable-optimizations	Profile-guided optimization	configure.ac
--enable-experimental-jit	Enable JIT compiler	configure.ac Python/jit.c
--disable-gil	Free-threading mode	configure.ac affects all runtime code
Py_DEBUG	Debug builds with assertions	pyconfig.h
Py_REF_DEBUG	Reference count debugging	Include/object.h

Runtime Configuration

• PyConfig: Main configuration structure Include/cpython/initconfig.h
• Environment variables: PYTHONPATH, PYTHONHOME, PYTHONOPTIMIZE, etc.
• -X options: -X dev, -X utf8, -X tracemalloc, etc.
• sys.flags: Access configuration from Python

Configuration processing: Python/initconfig.c

Optimization Levels

Level	Effect	Bytecode Changes
-O	Basic optimization	Remove assert statements, __debug__ = False
-OO	Remove docstrings	Also remove __doc__ attributes

Sources: Python/initconfig.c1-100 configure.ac Include/cpython/initconfig.h

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