Diagnosing <py-config> Package Loading Failures in PyScript

Solving Package Import Failures in PyScript

The most common failure point in PyScript applications is the ImportError or NameError occurring within a <py-script> block, despite the required package being listed in the configuration. This typically happens because the PyScript runtime has not yet resolved the package dependencies before the script execution begins.

Diagnostic Quick-Reference

Symptom	Likely Cause	Primary Check
ImportError: No module named 'X'	Tag placement or misspelling	Verify <py-config> is above <py-script>
Package loads but is not available globally	Autoload configuration	Check autoload attribute value
Browser console reports CSP violation	Security Policy restriction	Inspect script-src in DevTools
Package fails to initialize/crash	Non-pure-Python wheel	Check if package requires C-extensions

Ordered Diagnostic Checks

1. Verify Tag Order

   PyScript parses the HTML document sequentially. The <py-config> tag must be placed before any <py-script> or <py-repl> blocks that depend on those packages.

   • Action: Inspect the HTML source. Ensure <py-config> is the first PyScript-related tag in the <body>.
   • Risk: Placing the config after the script results in the runtime attempting to execute Python code before the package manager has fetched the required wheels.
2. Validate Package Syntax

   Packages must be listed as a comma-separated string within the packages attribute. Only pure-Python wheels from PyPI are supported by default.

   <!-- Correct Implementation -->
   <py-config packages="requests,pytz" autoload="true"></py-config>

   • Action: Check for typos in package names. Open the browser DevTools Network tab and filter by "whl" to see if the browser is actually attempting to fetch the file from the PyScript CDN.
   • Expected Result: A successful 200 OK response for the .whl file.
3. Evaluate the Autoload State

   The autoload attribute determines if the package is automatically imported into the global namespace.

   • Action: If autoload="false", you must explicitly call import package_name inside your <py-script> block.
   • Verification: Set autoload="false", add import requests to your script, and verify the code runs. If it still fails, the issue is the fetch process, not the autoload setting.
4. Check Content Security Policy (CSP)

   Strict CSP headers can block the browser from downloading wheels from the PyScript CDN.

   • Action: Open the browser console. Look for errors stating: Refused to load the script... because it violates the following Content Security Policy directive.
   • Fix: Update your server headers or <meta> tag to allow script-src from the PyScript domain.
5. Confirm Wheel Compatibility

   PyScript runs in a WebAssembly (WASM) environment. Packages requiring compiled C-extensions (unless specifically built for Pyodide/PyScript) will fail to load.

   • Action: Attempt to load a known pure-Python package (e.g., requests). If the pure-Python package works but your target package fails, the target likely requires native binaries.

Resolution Path

• Misspelled Package: Correct the string in packages="..." and refresh.
• Wrong Order: Move the <py-config> tag to the top of the HTML body.
• CSP Block: Add the PyScript CDN URL to the script-src and connect-src directives.
• Binary Dependency: Search for a pure-Python alternative or check if the package is officially supported by the Pyodide distribution.

Escalation Criteria

If the following conditions are met and the package still fails to load, the issue is likely a version mismatch or a CDN outage:

• The <py-config> tag is correctly placed and spelled.
• The browser console shows no CSP violations.
• The Network tab shows a 404 error for a package that is known to exist on PyPI.
• The issue persists across different modern browsers (Chrome, Firefox, Edge).