PyScript Cache Staleness: When Do Wheel Artifacts Refresh Across Page Reloads?

PyScript does not automatically detect or refresh cached wheels simply because a new version has been published to a CDN. If the version identifier in your configuration remains the same, the browser will continue to serve the cached artifact from the Cache API or IndexedDB, regardless of whether a newer file exists at the remote URL.

Cache Invalidation Triggers

The PyScript loader uses version-specific identifiers to generate cache keys. Invalidation is typically triggered by the following changes:

• Version String Updates: Changing the version of a package within the py-config (e.g., moving from "pandas==1.5.0" to "pandas==1.5.1") forces the loader to fetch the new artifact because the cache key changes.
• Pyodide Runtime Bump: Updating the Pyodide version often invalidates existing wheels, as binaries are typically compiled for a specific Pyodide/Python version.
• Manual Intervention: Clearing the browser's site data or specifically emptying the "Cache Storage" via Developer Tools.

Likely Behavior vs. Confirmed Facts

While it is confirmed that PyScript relies on the browser's Cache API for persistence, there is a distinction between internal loader logic and HTTP caching:

Mechanism	Behavior	Status
Internal Cache Key	Tied to the specific version string in py-config.	Confirmed
CDN Headers	Cache-Control headers may cause the browser to skip the network check even if the internal cache is cleared.	Likely
Auto-Polling	The loader does not poll CDNs for "latest" updates on page reload.	Confirmed

Steps to Force a Refresh

1. Update the Config: Explicitly pin a newer version of the package in your py-config. This is the only programmatic way to ensure all users receive the update.
2. Manual Clear (Development):
   • Open Browser DevTools → Application tab.
   • Select Cache Storage in the left sidebar.
   • Right-click the PyScript/Pyodide cache and select Delete.
3. Hard Reload: Use Ctrl + F5 (or Cmd + Shift + R) to bypass the HTTP cache, though this may not always clear the Cache API storage.

Diagnostic Detail Needed: Are you using a specific Pyodide version pin in your configuration, or are you relying on the default PyScript versioning? This determines whether a global PyScript update will automatically trigger a runtime refresh for your users.