What are frozen modules in CPython, and why does editing their source change nothing?

## Three ways a module can be built into the interpreter It helps to separate three things that all sound like "compiled in". * A **builtin** module is written in C and linked into the executable; `sys.builtin_module_names` lists them and they have no Python source at all. * An **extension** module is C compiled to a shared library loaded at import time. * A **frozen** module is ordinary Python source whose *marshalled code object* was embedded in the executable at build time. It is Python code, and it behaves like any other module once imported — you can inspect it, monkeypatch it, reload considerations aside — but its bytecode came from the binary, not from a file. ## Why CPython freezes anything The import system is written in Python. That is a bootstrap problem: to import the module that implements importing, the interpreter would have to import something. Freezing solves it — the bootstrap import machinery is embedded in the binary and executed directly at startup, before any filesystem-based importer exists. Python 3.11 extended this from the bootstrap to a small set of modules that every interpreter start needs anyway. Each frozen module is a directory scan, an open, a read and an unmarshal that no longer has to happen, which is measurable on a process that starts thousands of times. `importlib.machinery.FrozenImporter` is the finder and loader that serves them, and it is consulted before path-based finders, so a frozen module wins over any file with the same name on `sys.path`. ## Why this leaf cares Everything the bytecode cache does is about deciding whether a file on disk is still authoritative: match the magic number, compare the recorded mtime and size, or re-hash the source. A frozen module has **no disk file in that role at all**. There is no validation step, no `__pycache__` entry, and nothing to invalidate. The code object was fixed when the interpreter was built, and the only thing that changes it is building a new interpreter. That produces a memorable failure: edit the source of a frozen stdlib module in a checkout, restart, and observe nothing change — not because a cache went stale, but because the file you edited was never consulted. Deleting `__pycache__`, touching the file and recompiling all have exactly zero effect, which is why the symptom is so confusing to anyone reasoning about `.pyc` invalidation. ## The escape hatch `-X frozen_modules=on` or `off` decides whether frozen modules are used. The default is **on** for an installed interpreter, where the stdlib is not expected to change under you, and **off** for a locally built one, so that a contributor editing stdlib source sees their edits without rebuilding. Turning it off makes the interpreter fall back to importing those modules from files in the normal way, at a small startup cost. A quick way to tell what you are dealing with is the module's spec. A frozen module reports `origin` as the literal string `'frozen'` rather than a path, and its loader is the frozen importer. Anything whose origin is a filename went through the ordinary source-or-cache path and obeys all the usual invalidation rules. ## What freezing is not It is not a distribution mechanism you reach for casually, and it is not the same as bundling an application into a single executable — that is a packaging concern, and those tools generally embed a zip archive of modules rather than freezing them into the interpreter binary. It is also not an optimization you enable. Frozen modules are already on in an installed interpreter; the flag exists to turn them *off*. A candidate who suggests enabling frozen modules in production for speed has the direction backwards. And it does not make a module immutable at runtime. Once imported, a frozen module is a perfectly ordinary module object in `sys.modules` whose attributes can be read, replaced or patched exactly like any other. Freezing fixes where the bytecode came from, nothing more.