Cache Granularity vs Build Speed: Per‑Dependency vs Full Requirements Cache Invalidation

Direct answer

Read the Docs historically invalidates the entire build environment cache whenever requirements.txt changes. Any edit—even a single version bump—forces a full reinstall of the Python environment. There is no documented per-dependency cache granularity, no configuration setting to enable it, and no public API to trigger a partial purge.

Confirmed facts vs. likely explanation

Established behavior: The platform appears to use a full-file hash as the cache key. Because the algorithm is internal and undocumented, you cannot predict invalidation from the file contents alone.

Uncertain: It is unclear whether recent platform updates have introduced finer-grained invalidation without public documentation. Do not assume per-dependency behavior unless you observe it directly in build logs.

Verification steps for your project

1. Run two builds that differ by exactly one dependency version in requirements.txt.
2. Compare the build logs. A full environment rebuild confirms whole-file invalidation; selective package reinstalls would indicate granular caching.
3. Check the official Read the Docs documentation and changelog for current statements on cache-key composition.

One diagnostic detail that would change the advice

If your build logs show that only the changed package is reinstalled after a single-line edit, share that detail. It would shift the recommendation from “expect full rebuilds” to “verify that granular caching is active and reliable.”

Practical implications

Since granularity is not configurable, the practical lever is dependency-tree size. A smaller requirements.txt reduces the cost of each full rebuild. If your plan supports custom build images, pre-installing dependencies in the image can avoid the requirements.txt cache path, but that moves update responsibility into your image pipeline.