Diagnosing PyScript Runtime Initialization and Pyodide Loading Failures

The Problem: The Infinite Loading Screen

PyScript applications often fail silently or hang on a loading indicator during the bootstrap phase. Because PyScript runs a full Python runtime (Pyodide) via WebAssembly (WASM) in the browser, the failure point is rarely the Python code itself, but rather the environment initialization, network delivery of the WASM binary, or browser security restrictions.

Quick Diagnostic Reference

Symptom	Likely Cause	Primary Check
Blank page / No output	Missing <py-config> or CDN block	Browser Console (F12)
SharedArrayBuffer error	Missing COOP/COEP Headers	Network Headers tab
Python Syntax Error at start	Config/Script order mismatch	HTML Source order
Extreme lag/Timeout	Overloaded packages list	Network Tab (Payload size)

Step-by-Step Initialization Audit

Follow these checks in order to isolate where the Pyodide runtime is failing to instantiate.

1. Verify Resource Delivery

PyScript must download the Pyodide WASM binary and the core JavaScript glue code. If your organization uses a strict Content Security Policy (CSP) or a firewall, these may be blocked.

• Open the Network Tab in Browser Developer Tools.
• Refresh the page and filter for .wasm or pyodide.
• Check: Look for 403 Forbidden or 404 Not Found. If these appear, your environment is blocking the Pyodide CDN.
• Risk: Using an outdated CDN link in the <script> tag can lead to version mismatches between the loader and the runtime.

2. Validate Tag Sequencing

PyScript parses the HTML document linearly. The runtime must know its configuration (dependencies and version) before it attempts to execute Python code.

Incorrect Order:

<py-script>
  import pandas
  print("Hello")
</py-script>
<py-config>
  packages = ["pandas"]
</py-config>

Correct Order:

<py-config>
  packages = ["pandas"]
</py-config>
<py-script>
  import pandas
  print("Hello")
</py-script>

If the script tag comes first, the runtime will attempt to import pandas before the config has told Pyodide to fetch the package, resulting in an ImportError.

3. Check for SharedArrayBuffer Restrictions

Advanced PyScript features and certain Pyodide optimizations require SharedArrayBuffer. For security reasons (mitigating Spectre/Meltdown), browsers only enable this if the page is "cross-origin isolated".

If you see errors regarding SharedArrayBuffer in the console, you must configure your web server to send the following HTTP headers:

• Cross-Origin-Embedder-Policy: require-corp
• Cross-Origin-Opener-Policy: same-origin

Verification: In the Network tab, click the main HTML document request and verify these two headers are present in the Response Headers section.

Fixing Common Configuration Errors

The <py-config> block is a TOML-like configuration. A single syntax error here can crash the entire bootstrap process.

Example of a stable configuration:

<py-config>
    packages = ["numpy", "matplotlib"]
    # Ensure the version is explicitly set if using a specific Pyodide release
    # pyodide_version = "0.25.0"
</py-config>

Diagnostic Decision: If the page loads but hangs for 30+ seconds, check the packages list. Each package adds to the initial WASM download and installation time. To resolve this, remove non-essential packages or move to a more lightweight alternative.

Escalation Criteria

If you have verified the following and the runtime still fails, the issue likely lies with browser compatibility or a regression in the specific PyScript version:

• Network tab shows 200 OK for all .wasm and .js files.
• <py-config> precedes <py-script>.
• COOP/COEP headers are active (if using multi-threading/SharedArrayBuffer).
• The browser is a modern Evergreen browser (Chrome, Firefox, Edge) with WASM enabled.

Rollback Procedure: To isolate whether the issue is your code or the runtime version, replace your current PyScript CDN link with the latest stable version from the official PyScript documentation and remove all custom packages from <py-config> to test a "bare-metal" load.