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: