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, covering Python 3.13, 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.
Standard Library: A comprehensive collection of modules providing OS interfaces, concurrency primitives, and data serialization.

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.rst48-71 Doc/whatsnew/3.15.rst48-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.

Sources: InternalDocs/README.md17-66 Doc/whatsnew/3.14.rst63-142 Doc/whatsnew/3.15.rst59-100

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/whatsnew/3.14.rst108-112

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. This tier includes Adaptive Specialization, where instructions are "quickened" into specialized forms after observing specific types at runtime. In 3.14+, this includes a new tail-calling interpreter Doc/whatsnew/3.14.rst108 In 3.15, the official Windows 64-bit binaries use this tail-calling interpreter by default Doc/whatsnew/3.15.rst96-97

Tier 2: Trace Optimizer

When a loop becomes "hot", the Tier 2 optimizer translates the bytecode into a trace of micro-operations (UOps). These UOps allow for more aggressive optimizations like guard elimination.

JIT Compilation

The JIT compiler (Python/jit.c) transforms Tier 2 UOp traces into native machine code. In Python 3.13, a basic JIT was added. In Python 3.14, binary releases for Windows and macOS officially support the experimental JIT Doc/whatsnew/3.14.rst138-139 Python 3.15 further significantly upgraded the JIT compiler Doc/whatsnew/3.15.rst95

Sources: InternalDocs/README.md40-44 Doc/whatsnew/3.14.rst108-139 Doc/whatsnew/3.15.rst95-97

Object System and Data Model

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

Singletons and Global Objects

CPython pre-allocates certain frequently used objects as singletons to save memory and time.

Small integers are initialized via _Py_small_ints_INIT Include/internal/pycore_runtime_init_generated.h15-227
Global strings (literals and identifiers) are managed in _Py_global_strings Include/internal/pycore_global_strings.h31-201
Static strings are interned during interpreter initialization in _PyUnicode_InitStaticStrings Include/internal/pycore_unicodeobject_generated.h12-165

Memory Management

CPython uses a reference-counting scheme with an optional generational garbage collector.

Incremental GC: Introduced in 3.14 to reduce pause times Doc/whatsnew/3.14.rst111
New Types: Python 3.15 adds a frozendict built-in type Doc/whatsnew/3.15.rst70-71 and a dedicated sentinel type Doc/whatsnew/3.15.rst72-73

Sources: Doc/whatsnew/3.14.rst111 Doc/whatsnew/3.15.rst70-73 Include/internal/pycore_runtime_init_generated.h15-227 Include/internal/pycore_global_strings.h31-201

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. 3.14 introduced significant standard library support for subinterpreters Doc/whatsnew/3.14.rst69-100
PyThreadState: State for an individual thread.
Free-threaded Mode: In 3.14, free-threaded Python is officially supported Doc/whatsnew/3.14.rst134-135 Python 3.15 provides a Stable ABI for free-threaded builds Doc/whatsnew/3.15.rst91-93

Sources: Doc/whatsnew/3.14.rst68-135 Doc/whatsnew/3.15.rst91-93

Standard Library and Core Modules

Data Serialization and Encodings

Zstandard: Official support via the compression.zstd module was introduced in 3.14 Doc/whatsnew/3.14.rst74-116
UTF-8: Python 3.15 uses UTF-8 as the default encoding Doc/whatsnew/3.15.rst82-83

Developer and Introspection Tools

Pdb: The Python Debugger is implemented in Lib/pdb.py Lib/pdb.py1-116 and relies on bdb.py Lib/bdb.py1
Remote Debugging: A safe external debugger interface for CPython was introduced in 3.14 Doc/whatsnew/3.14.rst106-107
Profiling: Python 3.15 includes the Tachyon high-frequency statistical sampling profiler Doc/whatsnew/3.15.rst74-77

New 3.15 Features

Explicit Lazy Imports: The lazy keyword defers module loading until first use Doc/whatsnew/3.15.rst107-149
Deferred Evaluation of Annotations: Annotations are no longer evaluated eagerly, improving performance Doc/whatsnew/3.14.rst148-168

Sources: Doc/whatsnew/3.14.rst74-168 Doc/whatsnew/3.15.rst74-149 Lib/pdb.py1-116

Build System and Configuration

CPython uses an autoconf-based build system on POSIX and MSBuild on Windows.

Diagram: Build System Components and Configuration

The current development version is defined in configure.ac as 3.16 configure.ac13 The core interpreter on Windows is managed via pythoncore.vcxproj PCbuild/pythoncore.vcxproj1-72

Sources: configure.ac1-18 PCbuild/pythoncore.vcxproj1-72 Doc/using/configure.rst1-43