Pip 24.2 Cache Key Generation: Unexpected Cache Misses on Minor Version Bumps

Answer

Pip 24.2 does not have a flag to make the cache key ignore transitive version changes; the key is a hash of the fully resolved requirement set, so any version bump—even if the resulting wheel is identical—produces a new cache key and a cache miss.

Confirmed Facts

• The pip cache lookup key is derived from a hash that includes the exact versions of all packages in the resolved dependency tree, environment markers, and platform tags.
• Changing a transitive dependency’s minor version changes that hash, causing a new cache entry even when the wheel file’s content hash stays the same.
• Pip’s documentation does not describe any configuration option to stabilize the cache key across version bumps; the design prioritizes reproducible environments over cache stability.

Likely Explanation for the Observed Misses

When you bump a minor version of a transitive dependency, pip’s resolver produces a different set of exact versions. The cache key changes, so pip treats the request as a miss and downloads the wheel again, even though the wheel file is byte‑for‑byte identical to the previously cached one.

Steps to Verify or Mitigate

1. Check the current cache contents: pip cache list (or inspect $PIP_CACHE_DIR directly).
2. After a version bump, run the install with --report report.json and compare the installed entries to see if the same wheel hash appears under a new cache entry.
3. If you want to reduce misses without sacrificing reproducibility, consider using version ranges (e.g., package>=1.2.0,<2.0.0) in your top‑level requirements so that minor bumps do not force a new exact version set.
4. As a last resort, bypass the cache for a specific install with --no-cache-dir if you prefer to accept the download cost.

Missing Diagnostic Detail

Are you pinning exact versions in your top‑level requirements file, or are you using version ranges? Knowing this determines whether switching to ranges would eliminate the misses.