Overview

Relevant source files

• Doc/glossary.rst
• Doc/library/base64.rst
• Doc/library/binascii.rst
• Doc/library/functions.rst
• Doc/library/mimetypes.rst
• Doc/library/stdtypes.rst
• Doc/library/string.rst
• Doc/library/string.templatelib.rst
• Doc/library/text.rst
• Doc/library/threadsafety.rst
• Doc/reference/compound_stmts.rst
• Doc/reference/datamodel.rst
• Doc/reference/expressions.rst
• Doc/reference/lexical_analysis.rst
• Doc/whatsnew/3.14.rst
• Doc/whatsnew/3.15.rst
• Include/internal/pycore_global_objects_fini_generated.h
• Include/internal/pycore_global_strings.h
• Include/internal/pycore_runtime_init_generated.h
• Include/internal/pycore_unicodeobject_generated.h
• InternalDocs/README.md
• InternalDocs/changing_grammar.md
• InternalDocs/code_objects.md
• InternalDocs/compiler.md
• InternalDocs/exception_handling.md
• InternalDocs/frames.md
• InternalDocs/generators.md
• InternalDocs/interpreter.md
• InternalDocs/jit.md
• InternalDocs/parser.md
• InternalDocs/string_interning.md
• InternalDocs/structure.md
• Lib/base64.py
• Lib/mimetypes.py
• Lib/test/mime.types2
• Lib/test/test_base64.py
• Lib/test/test_binascii.py
• Lib/test/test_builtin.py
• Lib/test/test_mimetypes.py
• Misc/NEWS.d/next/Library/2026-04-20-01-24-22.gh-issue-92455.vXhmad.rst
• Misc/NEWS.d/next/Library/2026-05-12-14-44-39.gh-issue-149720.ccsoW-.rst
• Misc/NEWS.d/next/Library/2026-06-10-00-00-01.gh-issue-117807.Cx1178.rst
• Modules/binascii.c
• Modules/clinic/binascii.c.h
• Objects/clinic/enumobject.c.h
• Python/bltinmodule.c
• Python/clinic/bltinmodule.c.h

Purpose and Scope

CPython is the reference implementation of the Python programming language, written in C. This document provides a high-level architectural overview of CPython (including milestones from 3.13 through 3.15), outlining its main subsystems and their interrelations.

The structure of the CPython source code and major components follows conventions described in InternalDocs/structure.md which organizes code by feature and component responsibilities.

This page serves as a parent overview linking to specialized child pages for deeper detail on distinct topics such as compilation, execution, runtime infrastructure, and the standard library.

Major architectural components:

• Compilation Pipeline: Converts Python source code into executable bytecode via parsing, AST building, symbol table creation, control flow graph construction, and bytecode assembly.
• Execution Systems: A multi-tiered runtime with a tier 1 bytecode interpreter, adaptive specialization and quickening, a tier 2 trace-based optimizer, and just-in-time (JIT) compilation to native code.
• Object System: A unified object model built around PyObject with PyTypeObject metaclasses, implementing reference counting and cycle-detecting garbage collection.
• Runtime Infrastructure: Structures like _PyRuntimeState, PyInterpreterState, and PyThreadState manage interpreter and thread lifecycles, the Global Interpreter Lock (GIL), and subinterpreter support.
• Standard Library: A rich collection of modules providing OS interfaces, concurrency, data formats, cryptography, and much more.

Child pages provide detailed documentation about:

• Code Compilation Pipeline
• Code Execution Systems
• Object System and Memory Management
• Runtime Infrastructure
• Standard Library - Core Modules
• Build System and Development Infrastructure

Sources: Doc/whatsnew/3.14.rst48-71 Doc/whatsnew/3.15.rst48-100 InternalDocs/structure.md

---

CPython Architecture: Major Components

Diagram: CPython Architecture - Data Flow and Key Code Entities

This diagram illustrates the flow of Python source code through parsing, compilation, interpretation, optimization, and execution, highlighting core code entities, files, and functions.

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

---

Bytecode Definition and Generation System

CPython defines its bytecode instructions in a single authoritative source written in C with a declarative DSL:

• Source: Python/bytecodes.c defines instructions and micro-ops with macros like inst(), op(), macro(), and family().
• Generators: Python scripts in Tools/cases_generator/ process this file to generate tier-specific C code.
• Generated: The generated files include Python/generated_cases.c.h, executor_cases.c.h, optimizer_cases.c.h, and opcode metadata headers.
• Consumers: These generated files are included in core interpreter and optimizer source files such as Python/ceval.c and Python/optimizer.c.

Instruction Definition Macros

Macro	Purpose
inst(name, stack_effect)	Defines a Tier 1 bytecode instruction visible to the main interpreter.
op(name, stack_effect)	Defines a micro-operation (UOp) used internally by the Tier 2 trace optimizer.
macro(name)	Defines composite instructions that expand into multiple micro-ops.
family(name, ...)	Groups instructions for specialization (adaptive quickening).

Sources: InternalDocs/README.md31-40 Doc/whatsnew/3.14.rst108-112

---

Execution Model: Three-Tier Architecture

CPython executes bytecode using a three-tier execution system optimized for fast startup, quick steady-state execution, and high-performance native code:

Tier 1: Bytecode Interpreter

• The core evaluation loop is implemented in _PyEval_EvalFrameDefault (Python/ceval.c).
• Implements the classic stack-based interpreter with opcode dispatch.
• Supports Adaptive Specialization: frequently executed code triggers rewriting of bytecode into specialized forms with inline caches (quickening).
• 3.14 introduced a new tail-calling interpreter variant enhancing call performance.
• 3.15 Windows official binaries use this tail-calling interpreter by default.

Tier 2: Trace-Based Optimizer

• When backward jumps (loops) become hot, the Tier 2 optimizer activates.
• Transforms bytecode traces into sequences of micro-operations (UOps).
• Applies optimizations like redundant guard elimination and code motion.
• Generates optimized executors (_PyExecutorObject) that implement the trace logic.

JIT Compilation

• The JIT compiler (Python/jit.c) compiles optimized UOp traces into native machine code using a stencil mechanism.
• Python 3.13 introduced an experimental JIT.
• 3.14 and 3.15 significantly expanded and stabilized JIT support, including official platform binaries supporting it.

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

---

Object System and Data Model

CPython models all data as objects. Each object has a unique identity, immutable type, and mutable or immutable value.

Core Object Structures

• PyObject: Base structure for all objects, with reference count and type pointer.
• PyTypeObject: Defines type metadata and behavior for objects.
• Reference counting macros (Py_INCREF, Py_DECREF) manage object lifetimes.
• Optional cyclic garbage collector detects and frees circular references.

Special Singletons and Global Objects

• Small integers are pre-allocated in a singleton array (_Py_small_ints_INIT) for performance optimization.
• Global interned strings and identifiers are stored in _Py_global_strings and initialized on startup via _PyUnicode_InitStaticStrings.

Memory and GC Enhancements

• Python 3.14 introduced incremental garbage collection to reduce pause times.
• Python 3.15 added built-in types like frozendict and a sentinel type to improve type clarity.

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

---

Runtime Infrastructure

CPython runtime state is divided into multiple hierarchical structures:

• _PyRuntimeState: Represents global interpreter runtime state for the whole process.
• PyInterpreterState: Maintains state for an individual interpreter instance including modules, builtins, GIL state, and garbage collection.
• PyThreadState: Holds state for each thread including frame stack, current interpreter, and recursion counters.
• Free-threading and Subinterpreters: Python 3.14 introduced official support for free-threaded Python and improved subinterpreter integration. This continued with community and Stable ABI support in 3.15.

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

---

Standard Library and Core Modules

The CPython standard library provides modules spanning IO, concurrency, data serialization, networking, and more.

Recent Enhancements

• Compression: Official support for Zstandard (compression.zstd module) introduced in 3.14.
• Encoding: UTF-8 is now the default file system encoding in 3.15.
• Profiling Tools: 3.15 introduced a dedicated profiling package and the Tachyon high-frequency sampling profiler.
• Annotations: Deferred evaluation of type annotations was introduced in 3.14 to improve performance.
• Lazy Imports: 3.15 added explicit support for lazy imports with new lazy keyword and runtime flags to improve startup performance.
• Debugger and Remote Debugging: Python Debugger (pdb) implemented within the standard library; 3.14 added safe remote debugging interfaces.

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

---

Build System and Configuration

The CPython build system supports cross-platform building and configuration:

• The autoconf system for POSIX platforms driven by configure.ac.
• Generated scripts like configure (via Tools/build/regen-configure.sh) produce Makefiles.
• Windows builds use MSBuild projects in PCbuild/ such as pythoncore.vcxproj.
• Configuration headers like pyconfig.h are generated from templates during build configure.
• Windows build is documented in PCbuild/readme.txt.

The current development version is defined as 3.16 in configure.ac.

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

---

For detailed guidance on obtaining, configuring, and building CPython, see the child page:
Getting Started and Configuration

---

This overview provides a map of CPython’s architecture, emphasizing code entities, file locations, and the flow of execution from source code to runtime behavior. For each major component, consult the dedicated child pages for deeper technical information.