Python/C API reference manual — Python 3.14.3 documentation

Python/C API reference manual¶ This manual documents the API used by C and C++ programmers who want to write extension modules or embed Python. It is a companion to Extending and Embedding the Python Interpreter, which describes the general principles of extension writing but does not document the API functions in detail. Introduction Language version compatibility Coding standards Include Files Useful macros Objects, Types and Reference Counts Exceptions Embedding Python Debugging Builds Recommended third party tools C API Stability Unstable C API Stable Application Binary Interface Platform Considerations Contents of Limited API The Very High Level Layer Available start symbols Stack Effects Reference Counting Exception Handling Printing and clearing Raising exceptions Issuing warnings Querying the error indicator Signal Handling Exception Classes Exception Objects Unicode Exception Objects Recursion Control Exception and warning types Tracebacks Defining extension modules Multiple module instances Initialization function Multi-phase initialization Legacy single-phase initialization Utilities Operating System Utilities System Functions Process Control Importing Modules Data marshalling support Parsing arguments and building values String conversion and formatting Character classification and conversion PyHash API Reflection Codec registry and support functions PyTime C API Support for Perf Maps Abstract Objects Layer Object Protocol Call Protocol Number Protocol Sequence Protocol Mapping Protocol Iterator Protocol Buffer Protocol Concrete Objects Layer Fundamental Objects Numeric Objects Sequence Objects Container Objects Function Objects Other Objects C API for extension modules Interpreter initialization and finalization Before Python initialization Global configuration variables Initializing and finalizing the interpreter Cautions regarding runtime finalization Process-wide parameters Thread states and the global interpreter lock Detaching the thread state from extension code Non-Python created threads Supporting subinterpreters in non-Python threads Cautions about fork() High-level APIs GIL-state APIs Low-level APIs Asynchronous notifications Operating system thread APIs Synchronization primitives Python critical section API Legacy locking APIs Thread-local storage support Thread-specific storage API Dynamic allocation Methods Legacy APIs Multiple interpreters in a Python process A per-interpreter GIL Bugs and caveats High-level APIs Low-level APIs Advanced debugger support Profiling and tracing Reference tracing Python Initialization Configuration PyInitConfig C API Configuration Options Runtime Python configuration API PyConfig C API Py_GetArgcArgv() Delaying main module execution Memory Management Overview Allocator Domains Raw Memory Interface Memory Interface Object allocators Default Memory Allocators Customize Memory Allocators Debug hooks on the Python memory allocators The pymalloc allocator The mimalloc allocator tracemalloc C API Examples Object Implementation Support Allocating Objects on the Heap Object Life Cycle Common Object Structures Type Object Structures Supporting Cyclic Garbage Collection API and ABI Versioning Build-time version constants Run-time version Bit-packing macros Monitoring C API Generating Execution Events Managing the Monitoring State © Copyright 2001 Python Software Foundation. This page is licensed under the Python Software Foundation License Version 2. Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License. See History and License for more information. The Python Software Foundation is a non-profit corporation. Please donate. Last updated on Feb 28, 2026 (07:29 UTC). Found a bug? Created using Sphinx 8.2.3.