Declarative Python Dependencies in PyScript with <py-env>

Why manual bundling hurts interactive Python on the web

When you try to run Python code in the browser with PyScript, you must make sure every third‑party package your script imports is available at runtime. The usual workflow is to download the package’s Wheel, convert it to a WebAssembly module, and list each file in a <py-script> block or a separate micropip install call. Forgetting a dependency leads to silent import errors that appear only after the page has loaded, forcing you to open the console and trace the missing module. This manual step‑by‑step approach defeats the promise of “write Python, run it anywhere” because the developer becomes a bundle manager.

How <py-env> works

The <py-env> tag is a declarative way to list required pure‑Python or Wheel‑compatible packages. When the PyScript runtime parses the HTML, it collects the whitespace‑separated package names inside the tag and, after the core interpreter and standard library have been loaded as WebAssembly, it invokes micropip to fetch each package from PyPI, compile any needed Wheel to WASM, and install it into the isolated PyScript environment. The installation happens asynchronously, but PyScript delays the execution of any <py-script> blocks until all requested packages report success, ensuring that import statements inside those blocks will not raise ModuleNotFoundError. If a package fails to resolve, an error is printed to the developer console and dependent scripts are not executed.

Worked example: plotting with NumPy and Matplotlib

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script defer src="https://pyscript.net/latest/pyscript.js"></script>
</head>
<body>
  <py-env>
    numpy
    matplotlib
  </py-env>
  <canvas id="plot" width="400" height="300"></canvas>
  <py-script>
    import numpy as np
    import matplotlib.pyplot as plt
    from pyscript import display

    x = np.linspace(0, 2*np.pi, 200)
    y = np.sin(x)
    fig, ax = plt.subplots()
    ax.plot(x, y)
    ax.set_title('Sine wave')
    display(fig, target='plot')
  </py-script>
</body>
</html>

To try this example, copy the snippet into a file named plot.html and open it in a recent Chrome, Firefox, or Edge browser. Open the developer console; you should see lines similar to:

• [micropip] Installing numpy ...
• [micropip] Installing matplotlib ...
• [micropip] Success

If the installation succeeds, the canvas element displays a sine wave. If any line shows an error, the package either does not have a pure‑Python Wheel or the required compiled extensions are unavailable in the PyScript WASM build.

Trade‑offs and limitations

The convenience of <py-env> comes with two practical costs. First, each package adds its compiled Wheel to the initial download; a typical NumPy build is several megabytes of WASM, and Matplotlib pulls in additional dependencies, so the first page load can take several seconds on a modest connection. Second, because micropip runs after the base interpreter is ready, import errors surface only in the console after the network activity finishes, which can make early debugging less immediate than a syntax error that appears during HTML parsing. Finally, packages that rely on compiled C extensions not yet ported to the PyScript WASM target (for example, scipy or pandas with certain optional features) either fail to install or inflate the bundle size dramatically, limiting the set of libraries you can safely declare in <py-env>.

Actionable closing

Start with the template above, replace numpy and matplotlib with the packages you need, and keep an eye on the console for micropip feedback. For version‑specific notes—such as which Wheels are hosted on the PyScript CDN or how to pin a exact version—consult the official PyScript documentation. Experimenting with <py-env> lets you move from manual bundle management to a declarative workflow that mirrors the way you handle dependencies in a traditional Python project.