Why does preloading a Python app before forking workers save less memory than copy-on-write suggests?

## Copy-on-write is a promise about pages, not about objects When a pre-fork server imports the entire application in the parent and only then calls `os.fork()` once per worker, the child does not receive a copy of the parent's heap. It receives the same physical pages, mapped into both processes and marked read-only in both page tables. The first time either process writes to such a page the CPU traps, the kernel copies that one page (typically 4 KiB) into a private frame, and only then lets the write land. That is **copy-on-write**, and it is the whole reason "import once, fork N times" can host twenty workers for far less than twenty times the memory of one. The Python-specific catch is that CPython's heap is not read-mostly. Every object starts with a header holding a **reference count**, incremented whenever a new reference is taken and decremented when one goes away. Binding a name, appending the object to a list, passing it as an argument, iterating a container that holds it, calling a method on it — each of those is an ordinary read at the language level and a write at the memory level. The writes are also badly scattered: a table loaded at import time can have its keys and values spread across hundreds of pages, so touching a handful of entries dirties a handful of entire pages, not a handful of bytes. The **cyclic garbage collector** compounds this. Every container CPython tracks — lists, dicts, instances with a `__dict__`, tuples containing containers — carries collector bookkeeping alongside the refcount, and a collection walks the generation updating that bookkeeping in place. One full collection inside a worker can therefore touch nearly every preloaded container it still reaches, un-sharing a large slice of the supposedly shared heap in a single sweep. The classic symptom is a fleet whose workers look wonderfully cheap for the first minute and then converge, over an hour, on roughly the footprint they would have had with no preloading at all. ## What actually helps - `gc.freeze()`, available since 3.7, is the direct mitigation. Called after the application is imported and before the fork, it moves every currently tracked object into a **permanent generation** that collections skip, so the collector stops writing to those headers and the parent's constant data really does stay shared. The price is that frozen objects are never collected while frozen, which is why the call belongs immediately after imports rather than after the process has been running and churning; a child that genuinely needs those objects collected can call `gc.unfreeze()`. - **Data shape** matters more than any flag. A million small objects means a million refcounted headers spread over a lot of pages. The same payload held as `bytes`, an `array.array`, or a memory-mapped file has one header and a contiguous block, and nothing in the interpreter writes into that block just because you read it. If the point of preloading is to share a large read-mostly table, choosing a representation with few object headers beats every piece of GC tuning available. - Since 3.12, PEP 683 made a set of objects **immortal** — `None`, `True`, `False`, small integers, interned strings — meaning their counts are pinned and no longer updated on every reference. That removes a genuine source of dirtying, because those are precisely the objects every code path touches. On the free-threaded build, officially supported from 3.14, reference counting is implemented differently again, so the only honest answer to "how much did preloading save" is a measurement taken on the build you actually ship. ## Measuring it Adding up per-process **resident set size** is the standard mistake: a shared page is counted once for every process that maps it, so the total is inflated and preloading looks like it did nothing. On Linux, **proportional set size** divides each shared page among its sharers, and the per-process smaps rollup separates shared-clean from private-dirty pages. The number worth graphing is **private-dirty growing over a worker's lifetime** — that is the shared heap being un-shared, one page fault at a time. `resource.getrusage(resource.RUSAGE_SELF)` reports a peak in its `ru_maxrss` field, which answers "how big" and never "how shared". ## Where this sits in the preload tradeoff Preloading buys three things: - shared pages, - a fast worker start with no re-import, - and a single place where an import error surfaces. It costs the discipline of never carrying an inherited connection into a child, and it means the sharing benefit decays rather than holding. Treat it as a measured optimisation with a number attached, not as an architectural guarantee.