Exploring CPython’s Internals

This is a quick guide for people who are interested in learning more about CPython’s internals. It provides a summary of the source code structure and contains references to resources providing a more in-depth view.

CPython Source Code Layout

This guide gives an overview of CPython’s code structure. It serves as a summary of file locations for modules and builtins.

For Python modules, the typical layout is:

• Lib/<module>.py

• Modules/_<module>.c (if there’s also a C accelerator module)

• Lib/test/test_<module>.py

• Doc/library/<module>.rst

For extension-only modules, the typical layout is:

• Modules/<module>module.c

• Lib/test/test_<module>.py

• Doc/library/<module>.rst

For builtin types, the typical layout is:

• Objects/<builtin>object.c

• Lib/test/test_<builtin>.py

• Doc/library/stdtypes.rst

For builtin functions, the typical layout is:

• Python/bltinmodule.c

• Lib/test/test_builtin.py

• Doc/library/functions.rst

Some exceptions:

• builtin type int is at Objects/longobject.c

• builtin type str is at Objects/unicodeobject.c

• builtin module sys is at Python/sysmodule.c

• builtin module marshal is at Python/marshal.c

• Windows-only module winreg is at PC/winreg.c

Additional References

For over 20 years the CPython code base has been changing and evolving. Here’s a sample of resources about the architecture of CPython aimed at building your understanding of both the 2.x and 3.x versions of CPython:

Current references

Title	Brief	Author	Version
A guide from parser to objects, observed using GDB	Code walk from Parser, AST, Sym Table and Objects	Louie Lu	3.7.a0
Green Tree Snakes	The missing Python AST docs	Thomas Kluyver	3.6
Yet another guided tour of CPython	A guide for how CPython REPL works	Guido van Rossum	3.5
Python Asynchronous I/O Walkthrough	How CPython async I/O, generator and coroutine works	Philip Guo	3.5
Coding Patterns for Python Extensions	Reliable patterns of coding Python Extensions in C	Paul Ross	3.4
Your Guide to the CPython Source Code	Your Guide to the CPython Source Code	Anthony Shaw	3.8

Historical references

Title	Brief	Author	Version
Python’s Innards Series	ceval, objects, pystate and miscellaneous topics	Yaniv Aknin	3.1
Eli Bendersky’s Python Internals	Objects, Symbol tables and miscellaneous topics	Eli Bendersky	3.x
A guide from parser to objects, observed using Eclipse	Code walk from Parser, AST, Sym Table and Objects	Prashanth Raghu	2.7.12
CPython internals: A ten-hour codewalk through the Python interpreter source code	Code walk from source code to generators	Philip Guo	2.7.8