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