Managing Client-Side Python Dependencies with PyScript and <py-config>

The Backend Bottleneck in Frontend Logic

Many web developers face a recurring dilemma: they have complex data processing logic written in Python, but they don't want to manage a dedicated Flask or FastAPI backend just to handle a few calculations or data transformations for the user. Traditionally, this meant rewriting the logic in JavaScript or maintaining a server infrastructure that adds latency and cost.

PyScript solves this by running Python directly in the browser via WebAssembly (Wasm). The critical challenge, however, is not just running Python, but ensuring the runtime has the necessary libraries—like NumPy or Pandas—available before the first line of code executes. This is where the <py-config> tag becomes the primary tool for dependency management.

How Orchestrates the Runtime

PyScript relies on Pyodide, a port of CPython to WebAssembly. Because the browser environment is isolated, it cannot simply run pip install against a local OS. Instead, the <py-config> element acts as a manifest that tells the Pyodide runtime exactly which assets to fetch from the network before the Python interpreter starts.

The configuration typically handles two types of dependencies:

• PyPI Packages: Libraries that have been compiled for Wasm. PyScript fetches these as "wheels" (pre-built binary packages) from a compatible repository.
• Local Files: Custom .py modules hosted on your own server, allowing you to keep your logic modular rather than stuffing hundreds of lines of code into an HTML file.

Practical Implementation: Data Processing in the Browser

To use PyScript, you must include the PyScript assets in your HTML head. The following example demonstrates how to configure the runtime to use NumPy for a client-side calculation without a backend server.

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://pyscript.net/releases/2024.1.1/core.css">
  <script type="module" src="https://pyscript.net/releases/2024.1.1/core.js"></script>

  <py-config>
    packages = ["numpy"]
    files = ["/utils/math_helpers.py"]
  </py-config>
</head>
<body>
  <div id="output"></div>

  <py-script>
    import numpy as np
    from math_helpers import custom_sum

    data = np.array([10, 20, 30, 40])
    result = custom_sum(data)
    display(f"The processed sum is: {result}", target="output")
  </py-script>
</body>
</html>

Execution and Verification

To verify this configuration is working, run the file through a local web server (e.g., python -m http.server) and check the following:

1. Network Tab: Open Browser Developer Tools (F12). You should see requests for pyodide.wasm and the numpy wheel file.
2. Console: Check for any "ModuleNotFoundError." If the <py-config> is missing the package, the script will fail immediately upon execution.
3. DOM Output: The display() function should inject the result directly into the #output div.

Trade-offs: Performance vs. Convenience

While moving Python to the frontend removes server overhead, it introduces a "cold start" problem. The browser must download the Pyodide runtime (several megabytes) and any specified packages before the script runs. This can lead to a noticeable delay—sometimes several seconds—where the page appears static.

Furthermore, there is a C-extension limitation. Not every package on PyPI works in PyScript. Because the code runs in Wasm, any library that relies on C-extensions must be specifically compiled for Pyodide. If you attempt to load a package that isn't pre-compiled for the Wasm target, the <py-config> load will fail.

Verification Checklist

Before deploying a PyScript application, verify your configuration using this decision matrix:

Scenario	Check	Risk
Using NumPy/Pandas	Included in packages list?	High initial load time.
Custom .py files	Correct relative path in files?	404 errors in Network tab.
Complex C-libs	Compatible with Pyodide?	Runtime crash/Import error.

By leveraging <py-config>, you can shift heavy data logic to the client's hardware, reducing your server costs and enabling offline-capable Python tools, provided you account for the initial payload size.