Object System and Memory Management

Relevant source files

• Doc/c-api/dict.rst
• Doc/c-api/object.rst
• Doc/c-api/refcounting.rst
• Doc/glossary.rst
• Doc/library/dis.rst
• Doc/library/functions.rst
• Doc/library/gc.rst
• Doc/library/io.rst
• Doc/library/site.rst
• Doc/library/stdtypes.rst
• Doc/library/string.rst
• Doc/library/string.templatelib.rst
• Doc/library/sys.rst
• Doc/library/sys_path_init.rst
• Doc/library/text.rst
• Doc/reference/compound_stmts.rst
• Doc/reference/datamodel.rst
• Doc/reference/expressions.rst
• Doc/reference/lexical_analysis.rst
• Doc/reference/simple_stmts.rst
• Doc/tutorial/classes.rst
• Doc/tutorial/controlflow.rst
• Doc/tutorial/datastructures.rst
• Doc/tutorial/inputoutput.rst
• Doc/tutorial/introduction.rst
• Include/cpython/dictobject.h
• Include/cpython/object.h
• Include/cpython/pystate.h
• Include/internal/pycore_ceval_state.h
• Include/internal/pycore_debug_offsets.h
• Include/internal/pycore_dict.h
• Include/internal/pycore_gc.h
• Include/internal/pycore_interp.h
• Include/internal/pycore_interp_structs.h
• Include/internal/pycore_object.h
• Include/internal/pycore_pystate.h
• Include/internal/pycore_setobject.h
• Include/internal/pycore_tstate.h
• Include/internal/pycore_typeobject.h
• Lib/test/mapping_tests.py
• Lib/test/test_builtin.py
• Lib/test/test_capi/test_object.py
• Lib/test/test_dict.py
• Lib/test/test_free_threading/test_set.py
• Lib/test/test_gc.py
• Lib/test/test_global.py
• Lib/test/test_set.py
• Lib/test/test_sys.py
• Lib/test/test_unpack_ex.py
• Modules/_testcapi/object.c
• Modules/clinic/gcmodule.c.h
• Modules/gcmodule.c
• Objects/clinic/setobject.c.h
• Objects/dictobject.c
• Objects/object.c
• Objects/setobject.c
• Objects/structseq.c
• Objects/typeobject.c
• Python/bltinmodule.c
• Python/ceval_gil.c
• Python/clinic/bltinmodule.c.h
• Python/clinic/sysmodule.c.h
• Python/gc.c
• Python/gc_free_threading.c
• Python/pylifecycle.c
• Python/pystate.c
• Python/sysmodule.c
• Tools/c-analyzer/cpython/ignored.tsv

This page provides an overview of CPython's object system and memory management architecture. Every Python value is represented as an object at the C level, with a common header that enables reference counting, type identification, and garbage collection.

Overview

CPython's object system consists of:

• PyObject structure - Base structure for all Python objects containing reference count and type pointer
• Type system (PyTypeObject) - Defines object behavior through slots and method resolution order
• Reference counting - Primary memory management via ob_refcnt (or biased counting in free-threaded builds)
• Garbage collector - Handles cyclic references that reference counting cannot resolve
• Container implementations - Optimized data structures like PyDictObject and PySetObject

Related pages:

• PyObject and Type System - Detailed coverage of object structure and type system
• Dictionary and Container Objects - Hash tables, sets, and their implementations
• Reference Counting and Garbage Collection - Memory management mechanisms
• Built-in Types and Functions - Standard types like int, str, list, dict
• Type Hinting and Annotations - Typing system and annotation evaluation

For how these objects are manipulated during execution, see Bytecode Interpreter and Tiered Optimization.

Object Hierarchy and Core Structures

PyObject and PyVarObject Base Structures

All Python objects begin with a PyObject header that provides identity, type information, and reference counting:

PyObject Layout

Key structures:

• PyObject - Base for fixed-size objects (int, float, type, etc.)
• PyVarObject - Base for variable-size objects (list, tuple, str, etc.) with ob_size field
• ob_refcnt - Reference count for memory management (default build)
• ob_ref_local/ob_ref_shared - Split reference counts (free-threaded build)
• ob_type - Pointer to the object's type (PyTypeObject)

Sources: Include/object.h124-166 Include/cpython/object.h1-50

Type System Components

The type system defines object behavior through PyTypeObject structures:

Type System Architecture

Key type system features:

• tp_dict - Contains methods and attributes accessible via lookup
• tp_mro - Method resolution order for inheritance
• tp_version_tag - Enables efficient cache invalidation when types change
• Type slots (tp_getattr, tp_setattr, tp_call, etc.) - Function pointers for operations
• Static vs heap types - Static builtins are shared across interpreters, heap types are per-interpreter

For detailed type system mechanics, see PyObject and Type System.

Sources: Objects/typeobject.c1-100 Objects/typeobject.c987-1048 Include/cpython/object.h155-403

Memory Management Strategy

Reference Counting

CPython's primary memory management mechanism is reference counting. Each object tracks how many references point to it:

Reference Counting Flow

Key functions:

• Py_INCREF(op) / Py_DECREF(op) - Increment/decrement reference count
• _Py_Dealloc(op) - Deallocate object when count reaches zero
• _Py_IsImmortal(op) - Check if object is immortal (never deallocated)
• Free-threaded build: _Py_ExplicitMergeRefcount(), _Py_brc_queue_object() for biased counting

Detailed reference counting mechanisms, including free-threaded biased reference counting, are covered in Reference Counting and Garbage Collection.

Sources: Include/object.h570-650 Objects/object.c334-431 Include/internal/pycore_object.h134-196

Garbage Collection

Reference counting cannot detect cyclic references (e.g., a list containing itself). CPython includes a garbage collector for this:

Garbage Collection Architecture

Generational GC:

• Generation 0 - Newly created objects, collected most frequently
• Generation 1 - Objects that survived one collection
• Generation 2 - Long-lived objects, collected least frequently
• Permanent generation - Objects that should never be collected

Key GC structures and functions:

• PyGC_Head - Linked list node for GC tracking (default build)
• _PyGC_TRACK(op) / _PyGC_UNTRACK(op) - Add/remove from GC tracking
• gc_collect_main() - Main collection entry point
• _PyGCState - Per-interpreter GC state in PyInterpreterState

See Reference Counting and Garbage Collection for detailed GC algorithms and cycle detection.

Sources: Python/gc.c1-173 Python/gc_free_threading.c1-108 Include/internal/pycore_gc.h115-180

Container Object Implementations

Dictionary (PyDictObject)

Dictionaries are the most critical container type in CPython, used for namespaces, object attributes, and general key-value storage:

Dictionary Structure

Key dictionary features:

• Compact hash table with separate indices and entries arrays
• Combined tables for general dictionaries (keys and values together)
• Split tables for instance dictionaries (shared keys, separate values per instance)
• Unicode-only optimization (DICT_KEYS_UNICODE) when all keys are strings
• Collision resolution via PERTURB_SHIFT and probing

Dictionary operations:

• dictkeys_get_index() - Map hash to entry index
• insertdict() - Insert key-value pair
• lookdict() / lookdict_unicode() - Key lookup
• dictresize() - Grow dictionary when load factor exceeded

For detailed hash table mechanics and split-table optimization, see Dictionary and Container Objects.

Sources: Objects/dictobject.c8-89 Objects/dictobject.c507-558 Include/internal/pycore_dict.h1-84

Sets (PySetObject)

Sets provide unordered collections with fast membership testing:

Set Structure

Set features:

• Hash table without values (keys only)
• Similar collision resolution to dictionaries
• Frozenset variant (immutable, hashable)
• Operations: set_add(), set_discard(), set_intersection(), set_union()

Sources: Objects/setobject.c1-46 Include/setobject.h

Free-Threading Considerations

Biased Reference Counting

The free-threading build implements biased reference counting to reduce contention:

This approach allows most reference counting operations to avoid expensive atomic operations when objects are accessed primarily by their creating thread.

Sources: Objects/object.c357-523 Include/internal/pycore_object.h345-412

Per-Thread Reference Counting

Certain high-frequency objects use specialized per-thread reference counting:

This optimization is particularly important for function calls, attribute access, and other operations that frequently manipulate type and code objects.

Sources: Include/internal/pycore_object.h325-412 Include/internal/pycore_uniqueid.h