PyPI Simple API cache freshness limits for yanked and new releases

Direct Answer

The PyPI Simple API index pages are served through Fastly with a Cache-Control: max-age=300 header (5 minutes) in typical observations, but this TTL is not officially documented and may vary by edge node. No automatic purge occurs when a release is yanked or added; the cached index can remain stale for up to the full TTL. Geographic region can affect which edge node serves the request, potentially exposing different cached content, though no regional TTL differences are published. Clients can compare the Age header to max-age to infer staleness, but Age is not always present or reliable.

Confirmed vs. Inferred Behavior

Confirmed (observable in responses)

• Simple index responses include Cache-Control: max-age=300 (observed via curl -I https://pypi.org/simple/).
• The Age header appears on cache hits and increments with time at the edge.
• Yanking a release updates the JSON API (/pypi/{project}/json) immediately; the HTML index does not reflect the change until the cached entry expires.

Inferred / Not Guaranteed

• The 300-second TTL is derived from observed headers; PyPI does not publish a canonical value and may change it without notice.
• Private mirrors or custom CDN configurations (e.g., corporate proxies) may apply different TTLs.
• No public purge API or webhook exists for project maintainers to invalidate a project's index page.
• Regional edge nodes operate independently; a request from one region may hit a fresh cache while another hits a stale one.

Practical Verification Steps

1. Run curl -I https://pypi.org/simple/{project}/ and record Cache-Control and Age.
2. Repeat from a different network (e.g., VPN, cloud shell) to observe potential regional variance.
3. Yank a test release (or use a project with recent yank) and immediately re-query the index; if the yanked release still appears, the cache has not been invalidated.
4. Compare the JSON API response (/pypi/{project}/json) with the HTML index to measure the divergence window.

Staleness Detection for Clients

If Age is present and Age > max-age, the response is stale. However:

• Age may be omitted on cache misses or by some edge configurations.
• Intermediary proxies may add or rewrite Age.
• Absence of Age does not guarantee freshness.

For critical operations (e.g., security-sensitive installs), bypass the cache with Cache-Control: no-cache or query the JSON API directly, which reflects yank status immediately.

Missing Diagnostic Detail

If you are observing a staleness window longer than 5 minutes consistently, provide the Age and Cache-Control values from two geographically distinct requests to the same project index. That data determines whether the cause is extended TTL, regional cache isolation, or an intermediary proxy.