Overview

Relevant source files

• Doc/c-api/object.rst
• Doc/c-api/refcounting.rst
• Doc/library/os.rst
• Doc/using/configure.rst
• Include/cpython/object.h
• Include/internal/pycore_ceval.h
• Include/internal/pycore_dict.h
• Include/internal/pycore_object.h
• Include/internal/pycore_opcode_metadata.h
• Include/internal/pycore_optimizer.h
• Include/internal/pycore_stackref.h
• Include/internal/pycore_typeobject.h
• Include/internal/pycore_uop_ids.h
• Include/internal/pycore_uop_metadata.h
• Lib/os.py
• Lib/test/support/os_helper.py
• Lib/test/test_capi/test_object.py
• Lib/test/test_capi/test_opt.py
• Lib/test/test_descr.py
• Lib/test/test_dict.py
• Lib/test/test_generated_cases.py
• Lib/test/test_pty.py
• Lib/test/test_xml_etree_c.py
• Makefile.pre.in
• Modules/_testcapi/object.c
• Modules/clinic/posixmodule.c.h
• Modules/posixmodule.c
• Objects/dictobject.c
• Objects/object.c
• Objects/typeobject.c
• PCbuild/_freeze_module.vcxproj
• PCbuild/_freeze_module.vcxproj.filters
• PCbuild/pythoncore.vcxproj
• PCbuild/pythoncore.vcxproj.filters
• Python/bytecodes.c
• Python/ceval.c
• Python/ceval_macros.h
• Python/executor_cases.c.h
• Python/generated_cases.c.h
• Python/optimizer.c
• Python/optimizer_analysis.c
• Python/optimizer_bytecodes.c
• Python/optimizer_cases.c.h
• Python/optimizer_symbols.c
• Python/stackrefs.c
• Tools/cases_generator/analyzer.py
• Tools/cases_generator/generators_common.py
• Tools/cases_generator/optimizer_generator.py
• Tools/cases_generator/stack.py
• Tools/cases_generator/tier1_generator.py
• Tools/cases_generator/tier2_generator.py
• Tools/tsan/suppressions_free_threading.txt
• configure
• configure.ac
• pyconfig.h.in

Purpose and Scope

This document provides a high-level architectural overview of CPython, the reference implementation of the Python programming language. It covers the major subsystems, their interactions, and the overall flow from Python source code to execution. This page serves as an entry point to understanding the codebase structure and design.

For detailed information on specific subsystems:

• Code execution mechanics: see Code Execution Pipeline
• Memory and object model: see Object System and Memory Management
• Concurrency and threading: see Runtime and Thread Management
• Building and configuration: see Build System and Configuration

What is CPython?

CPython is the canonical Python interpreter written in C. It transforms Python source code into bytecode, which is then executed by a virtual machine. The codebase is organized around several core responsibilities:

Component	Primary Location	Purpose
Bytecode Compiler	Python/compile.c, Python/flowgraph.c	Transforms AST to bytecode
Tier 1 Interpreter	Python/ceval.c, Python/generated_cases.c.h	Executes bytecode instructions
Tier 2 JIT Optimizer	Python/optimizer.c, Python/executor_cases.c.h	Optimizes hot code paths
Object System	Objects/ directory	Implements Python's data types
Runtime State	Python/pystate.c, Python/ceval_gil.c	Manages interpreter and thread state
Build System	configure.ac, Makefile.pre.in	Configures and builds CPython

Sources: Python/bytecodes.c1-50 Python/ceval.c1-50 Python/optimizer.c1-50 configure.ac1-50

Architecture Overview

Major Subsystems and Data Flow

Sources: Python/bytecodes.c1-100 Python/ceval.c1-300 Python/optimizer.c1-100 Python/generated_cases.c.h1-50 Python/executor_cases.c.h1-50

Core Components and Their Relationships

Sources: Python/bytecodes.c1-10 Python/ceval.c1-50 Python/pystate.c1-50 configure.ac1-50 Makefile.pre.in1-50

Tiered Execution Model

CPython implements a two-tier execution system to balance startup speed with long-running performance:

Tier 1: Bytecode Interpreter

The Tier 1 interpreter is the traditional bytecode execution engine defined in Python/ceval.c with instruction implementations generated from Python/bytecodes.c into Python/generated_cases.c.h

Key characteristics:

• Fast startup and low memory overhead
• Switch-based or computed goto dispatch in _PyEval_EvalFrameDefault()
• Adaptive specialization via inline caches
• Execution counters track hot code paths

Sources: Python/ceval.c1-300 Python/generated_cases.c.h1-100 Python/bytecodes.c1-150

Tier 2: JIT Optimizer and Executor

When code becomes "hot" (executed frequently), the Tier 2 system builds optimized traces:

Key components:

• Optimizer (Python/optimizer.c): Builds traces from bytecode, applies optimizations
• Analyzer (Python/optimizer_analysis.c): Performs data-flow analysis
• Executor (_PyExecutorObject): Executes optimized micro-operation sequences
• Micro-ops (Python/executor_cases.c.h): Low-level operations for Tier 2

Sources: Python/optimizer.c1-100 Python/optimizer_analysis.c1-50 Python/executor_cases.c.h1-100 Python/optimizer_bytecodes.c1-100

Object System Foundation

All Python objects share a common base structure and type system:

PyObject Hierarchy

Sources: Objects/object.c1-100 Objects/typeobject.c1-200 Objects/dictobject.c1-100

Dictionary Implementation

Dictionaries are central to Python's implementation, used for namespaces, class attributes, and instance storage:

Sources: Objects/dictobject.c1-100 Include/internal/pycore_dict.h1-50

Runtime State Hierarchy

CPython maintains a hierarchy of state objects that manage execution:

Sources: Python/pystate.c1-100 Python/ceval_gil.c1-50 Include/internal/pycore_pystate.h1-100

Build and Configuration System

CPython uses an autoconf-based build system that adapts to different platforms:

Configuration and Build Flow

Sources: configure.ac1-100 Makefile.pre.in1-100

Platform Abstraction

The posixmodule.c provides a unified OS interface:

Sources: Modules/posixmodule.c1-100 configure.ac300-400

Code Generation Pipeline

CPython generates several critical files from source definitions:

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

Memory Management Model

CPython uses reference counting as the primary memory management strategy, supplemented by a cyclic garbage collector:

Sources: Objects/object.c1-200 Modules/gcmodule.c1-100 Python/ceval.c100-150

Testing and CI Infrastructure

CPython has extensive testing infrastructure:

Test Type	Location	Purpose
Unit Tests	Lib/test/test_*.py	Test individual modules and features
Optimizer Tests	Lib/test/test_capi/test_opt.py	Test JIT optimizer behavior
CI Workflows	.github/workflows/*.yml	Automated testing across platforms
Build Tests	Tools/build/	Test build system

Sources: Lib/test/test_capi/test_opt.py1-100

Key Design Principles

1. Tiered Optimization: Balance startup speed (Tier 1) with long-running performance (Tier 2)
2. Generated Code: Most interpreter dispatch code is generated from bytecodes.c for maintainability
3. Reference Counting + GC: Predictable memory management with cycle detection
4. Platform Independence: Unified API (posixmodule.c) with platform-specific implementations
5. Adaptive Specialization: Instructions specialize based on runtime type information
6. Extensibility: C API for extension modules, standard library in Python

Sources: Python/bytecodes.c1-150 Python/ceval.c1-300 Python/optimizer.c1-100 Modules/posixmodule.c1-100