Runtime Infrastructure

Relevant source files

• Doc/library/sys.rst
• Include/cpython/pystate.h
• Include/exports.h
• Include/internal/pycore_ceval_state.h
• Include/internal/pycore_codecs.h
• Include/internal/pycore_debug_offsets.h
• Include/internal/pycore_import.h
• Include/internal/pycore_importdl.h
• Include/internal/pycore_interp.h
• Include/internal/pycore_interp_structs.h
• Include/internal/pycore_moduleobject.h
• Include/internal/pycore_pystate.h
• Include/internal/pycore_runtime.h
• Include/internal/pycore_runtime_init.h
• Include/internal/pycore_tstate.h
• Lib/test/test_import/__init__.py
• Lib/test/test_sys.py
• Misc/NEWS.d/next/Library/2025-09-12-07-30-13.gh-issue-138580.Qr_fSH.rst
• Modules/_testsinglephase.c
• Objects/moduleobject.c
• PC/launcher.c
• PC/python_uwp.cpp
• Python/ceval_gil.c
• Python/clinic/sysmodule.c.h
• Python/dynload_win.c
• Python/import.c
• Python/importdl.c
• Python/pylifecycle.c
• Python/pystate.c
• Python/sysmodule.c

Purpose and Scope

This document describes CPython's runtime infrastructure — the core system-level state management and APIs that support Python program execution. This includes the global runtime state hierarchy, interpreter and thread state management, the Global Interpreter Lock (GIL), lifecycle management, and system-level APIs exposed through the sys module.

For details about specific runtime state management and thread operations, see Interpreter State and Thread Management. For information about system module functionality and runtime APIs, see System Module and Runtime APIs. For execution-related infrastructure like the evaluation loop and frame management, see Bytecode Interpreter and Evaluation Loop. For the import machinery and module loading, see Import System and Module Loading.

Runtime State Hierarchy

CPython organizes its runtime state in a three-level hierarchy: a single global runtime, one or more interpreters, and one or more threads per interpreter.

Runtime State Structure

Sources: Python/pylifecycle.c123-124 Include/internal/pycore_runtime_init.h113-114 Include/internal/pycore_interp_structs.h1-30

State Management Components

Component	Type	Scope	Primary File
_PyRuntime	_PyRuntimeState	Process-wide global	Python/pylifecycle.c123-124
Interpreter State	PyInterpreterState	Per-interpreter	Include/internal/pycore_interp_structs.h11-16
Thread State	PyThreadState	Per-thread	Include/cpython/pystate.h66-206
Thread-Local Storage	_Py_tss_tstate	Thread-local	Python/pystate.c73

Sources: Python/pystate.c73-82 Python/pylifecycle.c123-124 Include/internal/pycore_interp_structs.h1-300

Global Runtime State

The _PyRuntimeState structure is a process-wide singleton that contains state shared across all interpreters. It is initialized via _PyRuntime_Initialize and finalized via _PyRuntime_Finalize.

Key Runtime State Fields

Sources: Include/internal/pycore_runtime_init.h39-114 Python/pylifecycle.c123-124

Runtime Initialization and Finalization

Runtime Initialization

• _PyRuntime_Initialize(): Initializes the global _PyRuntime singleton Python/pylifecycle.c131-145
• Only initialized once per process; subsequent calls return _PyStatus_OK() Python/pylifecycle.c139-142
• Uses _PyRuntimeState_INIT to set default values for allocators, threads, and the main interpreter Include/internal/pycore_runtime_init.h39-114

Runtime Finalization

• _PyRuntime_Finalize(): Cleans up global runtime state and resets runtime_initialized Python/pylifecycle.c148-152
• Py_IsFinalizing(): Checks if the runtime is currently shutting down Python/pylifecycle.c155-158

Sources: Python/pylifecycle.c126-158 Include/internal/pycore_runtime_init.h39-114

Interpreter State Management

Each PyInterpreterState represents an isolated Python interpreter. While interpreters share the _PyRuntime state, they maintain separate module dictionaries (modules), built-ins, and evaluation configurations.

Interpreter State Structure

Key interpreter state components defined in _PyInterpreterState_INIT:

Field	Purpose	File Reference
id	Unique interpreter identifier	Include/internal/pycore_interp_structs.h118
threads	Linked list of thread states	Include/internal/pycore_interp_structs.h120-122
ceval	Evaluation state (recursion limits, pending calls)	Include/internal/pycore_interp_structs.h107-116
gc	Garbage collector state (generations, thresholds)	Include/internal/pycore_interp_structs.h214-278
imports	Import machinery state (modules, importlib)	Python/import.c91-118
sysdict	sys module dictionary	Python/sysmodule.c88-91

Sources: Include/internal/pycore_interp_structs.h107-278 Include/internal/pycore_runtime_init.h116-168 Python/import.c91-118

Interpreter Creation and Feature Flags

Interpreters are created with specific feature flags that define isolation levels:

Flag	Meaning	Value
Py_RTFLAGS_USE_MAIN_OBMALLOC	Share memory allocator with main interpreter	Include/internal/pycore_interp.h79
Py_RTFLAGS_MULTI_INTERP_EXTENSIONS	Check extension module compatibility	Include/internal/pycore_interp.h82
Py_RTFLAGS_THREADS	Allow thread creation	Include/internal/pycore_interp.h85
Py_RTFLAGS_FORK	Allow os.fork()	Include/internal/pycore_interp.h91

Sources: Include/internal/pycore_interp.h71-95 Python/import.c51-58

Thread State Management

The PyThreadState (aliased as struct _ts) manages the execution context for a single thread.

Thread State Lifecycle

Thread State Binding

• bind_tstate(): Sets thread_id using PyThread_get_thread_ident() and initializes thread-specific memory (mimalloc) Python/pystate.c163-192
• _Py_tss_tstate: Thread-local storage pointer to the active PyThreadState Python/pystate.c73

Thread Status

• _status: Tracks initialization, binding, activation, and finalization stages Include/cpython/pystate.h78-101
• _whence: Indicates how the thread was created (e.g., _PyThreadState_WHENCE_THREADING) Include/cpython/pystate.h103-111

Sources: Python/pystate.c73-214 Include/cpython/pystate.h66-123

GIL and Synchronization

The Global Interpreter Lock (GIL) ensures only one thread executes Python bytecode at a time per interpreter (unless built with Py_GIL_DISABLED).

GIL Implementation (ceval_gil.c)

• Switch Interval: The interval (default 5000µs) determines how long a thread holds the GIL before a drop is requested Python/ceval_gil.c147-153
• Drop Request: gil_drop_request is checked by the evaluation loop to trigger a context switch Python/ceval_gil.c20-30
• Eval Breaker: tstate->eval_breaker is a bitfield checked every opcode; it combines GIL drop requests, pending calls, and instrumentation signals Include/cpython/pystate.h76 Python/ceval_gil.c72-99

Sources: Python/ceval_gil.c1-192 Include/cpython/pystate.h73-76

Import System and Module Loading

The import system manages the lifecycle of modules and prevents parallel imports of the same module from returning partially loaded objects.

• Locking: _PyImport_AcquireLock() uses a recursive mutex (IMPORT_LOCK) per interpreter to serialize imports Python/import.c152-162
• Module Registry: sys.modules is maintained in interp->imports.modules Python/import.c91-92
• Built-in Table: PyImport_Inittab defines the statically linked modules available for import Python/import.c65-73

Sources: Python/import.c65-170 Include/internal/pycore_interp_structs.h123

System Module and Runtime APIs

The sys module provides the primary interface for inspecting and modifying runtime state.

Core sys Functionality

• Attributes: Managed via PySys_GetAttr and PySys_SetObject, which interact with the interpreter's sysdict Python/sysmodule.c78-114
• Standard Streams: stdin, stdout, and stderr are initialized during startup and can be redirected Python/sysmodule.c9-10
• Exception Info: sys.exc_info() and sys.exception() provide access to the exc_info stack in the current PyThreadState Lib/test/test_sys.py101-162
• Audit Hooks: sys.audit() triggers security events that are processed by hooks registered via PySys_AddAuditHook Python/sysmodule.c382-390

Sources: Python/sysmodule.c1-212 Lib/test/test_sys.py101-162 Doc/library/sys.rst1-150

Lifecycle Management Summary

Phase	Key Function	Purpose
Runtime Init	_PyRuntime_Initialize	Initialize global _PyRuntime Python/pylifecycle.c131
Interp Init	_PyInterpreterState_New	Create PyInterpreterState Include/internal/pycore_interp.h99
Thread Init	_PyThreadState_New	Create PyThreadState Python/pystate.c1508
Finalization	_PyRuntime_Finalize	Cleanup global state Python/pylifecycle.c148

Sources: Python/pylifecycle.c126-158 Python/pystate.c1508-1609