Skip to main content

Python/frozen.c

cpython 3.14 @ ab2d84fe1023/Python/frozen.c

Python/frozen.c is the registry of frozen modules. A frozen module is a Python module whose compiled bytecode is embedded directly in the interpreter binary as a C byte array. This allows the interpreter to import importlib._bootstrap and friends without touching the filesystem.

Map​

LinesSymbolRole
1-40_PyImport_FrozenBootstrapArray of bootstrap frozen entries
41-80_PyImport_FrozenStdlibArray of stdlib frozen entries (3.11+)
81-120_PyImport_FrozenTestArray used in test builds
121-160_PyImport_FrozenModulesCombined lookup table

Reading​

struct _frozen​

// CPython: Include/import.h (referenced from frozen.c)
struct _frozen {
    const char *name;
    const unsigned char *code;
    int size;
    int is_package;
};

code points to a co_marshal-encoded code object. size is the byte length of code. is_package is 1 for __init__-style entries.

Bootstrap frozen modules​

The bootstrap entries include importlib._bootstrap and importlib._bootstrap_external. These are the first modules imported at interpreter startup before sys.path is configured. Because they are frozen they can be loaded without any filesystem operations.

Extended frozen stdlib (3.11+)​

CPython 3.11 added a much larger set of frozen stdlib modules (os, abc, codecs, encodings.*, etc.) to speed up startup time. The set is generated by the build system from the compiled Lib/ source files.

// CPython: Python/frozen.c:60 _PyImport_FrozenStdlib (abbreviated)
static const struct _frozen _PyImport_FrozenStdlib[] = {
    {"abc", _Py_M__abc, (int)sizeof(_Py_M__abc)},
    {"codecs", _Py_M__codecs, (int)sizeof(_Py_M__codecs)},
    ...
    {0, 0, 0}  /* sentinel */
};

gopy notes​

gopy uses stdlibinit/registry.go as its equivalent of frozen.c. Each built-in module is registered with its Go implementation rather than embedded bytecode. Frozen bytecode would require a working marshal decoder; using Go module registrations is simpler and does not require bytecode embedding.