How to Import External Python Packages in Pyscript Using the pip Directive

Why pip Works in Pyscript

Pyscript runs Python inside the browser by bundling Pyodide, a WebAssembly‑based Python interpreter. Pyodide ships with a lightweight pip implementation that can download and install packages from PyPI into the interpreter’s virtual file system at page load. The <py-config> tag lets you declare a list of packages to fetch before any <py-script> block runs, ensuring they are available when your code executes.

Declarative Package Loading

The pip option inside <py-config> accepts an array of package names. Pyodide resolves each name to the latest compatible wheel, downloads it, and installs it into the in‑browser environment. Example:

<py-config>
    pip = ["numpy", "requests"]
</py-config>

<py-script>
    import numpy as np
    import requests
    print("NumPy version:", np.__version__)
    print("Requests version:", requests.__version__)
</py-script>

Place the <py-config> block before any <py-script> tags; otherwise the interpreter starts without the requested packages and you’ll see an ImportError at runtime.

Under the Hood

• Pyodide’s pip wrapper fetches a wheel from PyPI.
• Wheel files are extracted into Pyodide’s virtual file system.
• Python modules are added to the interpreter’s sys.path automatically.
• All operations happen in the browser’s memory (IndexedDB) and are cached for subsequent page loads.

Supported Packages

Only packages that ship as pure‑Python wheels or that contain a pre‑compiled WebAssembly module can be installed. Packages that require native C extensions (e.g., numpy‑mkl, pandas‑extensions) will fail because the browser cannot compile arbitrary C code.

Typical Limitations

• Load time: Large wheels increase the initial page load and can push the browser’s memory quota. A heavy package like numpy may take several seconds to download and install.
• Storage quota: IndexedDB storage is limited (often ~50 MB). Repeatedly loading many large packages can exceed the quota and block further downloads.
• Network dependency: The pip directive requires an active internet connection. Offline mode will cause import failures.
• Missing native extensions: Attempts to install packages that need compiled extensions will raise errors or silently fail, leading to confusing runtime errors.

Common Mistakes and How to Avoid Them

1. Placing pip after <py-script> – Move the <py-config> block to the top of the document.
2. Using unsupported packages – Verify the package’s wheel on PyPI or test in a minimal page before production.
3. Ignoring network errors – Check the browser console for failed fetch requests to https://pypi.org/simple/….
4. Overloading the page with many large packages – Bundle only what you need; consider lazy‑loading or dynamic imports if possible.

Verification Checklist

• Open the page and confirm that the console prints the expected version string.
• In the browser’s Developer Tools, look under the Network tab for requests to pypi.org and confirm that the wheel files are downloaded.
• Navigate to Application → IndexedDB and verify that the pyodide database contains a site‑packages entry for the installed package.
• Reload the page with the network disabled (offline mode). The import should fail with a clear message such as ImportError: No module named 'numpy'.

Practical Example: Using NumPy in Pyscript

Below is a minimal HTML snippet that demonstrates a complete, working page. Replace YOUR‑URL with the location where you host the file.

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Pyscript NumPy Demo</title>
  <script src="https://cdn.jsdelivr.net/pyodide/v0.24.1/full/pyodide.js"></script>
  <script src="https://cdn.jsdelivr.net/pyodide/v0.24.1/full/pyscript.js"></script>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/pyodide/v0.24.1/full/pyscript.css">
</head>
<body>
  <py-config>
      pip = ["numpy"]
  </py-config>

  <py-script>
      import numpy as np
      print("NumPy version:", np.__version__)
  </py-script>
</body>
</html>

When you open this page, the console will display something like NumPy version: 1.26.4, confirming that the package was fetched and installed successfully.

Conclusion

Using the pip directive in <py-config> is the simplest way to bring external Python libraries into a Pyscript page. Keep the list lean, ensure the packages are pure‑Python wheels, and be mindful of network and storage constraints. With these guidelines, you can reliably extend your in‑browser Python applications without compromising performance or stability.