PyScript <py-config> packages: offline wheel resolution missing

Direct Answers

• Local wheel directory: No. Micropip only resolves wheels from PyPI; it cannot be pointed at a custom directory of pre‑downloaded wheels.
• Lockfile / hash‑based requirements: No. The <py-config> block does not accept a lockfile or a requirements.txt with exact hashes to pin versions for offline installs.
• Documented build‑time vendor/cache step: No. There is no official method to pre‑cache or vendor wheels during a build so that <py-config> operates without network access.

Why This Is the Case

PyScript’s package installation is handled by micropip, which is designed to fetch pure‑Python wheels exclusively from the public PyPI index. The <py-config> schema exposes a packages array of package names (optionally with version specifiers) but provides no parameters for:

• index-url or find-links style alternate repositories
• offline, vendor, or cache-dir flags
• Hash verification via --require-hashes or a lockfile

Consequently, every micropip.install() call requires a live connection to PyPI (or a compatible index that micropip knows how to query). The current PyScript documentation (as of the 2024‑2025 releases) does not describe any offline‑first workflow.

Practical Workarounds (Unofficial)

1. Vendor Wheels into Your Application Bundle

If you control the build pipeline, you can download the required wheels ahead of time and serve them alongside your HTML. Then, at runtime, use a custom micropip call that points to those local files:

<py-script>
import micropip
await micropip.install([
  "./wheels/requests-2.31.0-py3-none-any.whl",
  "./wheels/pydantic-2.5.3-py3-none-any.whl",
])
</py-script>

Caveats: The wheel filenames must match PyPI naming conventions exactly. You must also include all transitive dependencies. This approach bypasses <py-config> entirely and requires you to manage the dependency graph yourself.

2. Use a Local PyPI Mirror (e.g., devpi, pypiserver)

Run a lightweight PyPI mirror on the same air‑gapped network. Configure the browser to trust the mirror’s certificate (if HTTPS) and point micropip at it by monkey‑patching micropip.PYPI_URL before any install:

<py-script>
import micropip
micropip.PYPI_URL = "https://local-mirror.example.com/simple/"
await micropip.install(["requests", "pydantic"])
</py-script>

This keeps the <py-config> declaration intact but still requires a network service inside the air‑gapped environment.

3. Pre‑install Packages into a Custom Pyodide Build

Build a custom Pyodide distribution that includes your required packages. The Pyodide project documents adding packages at build time. The resulting pyodide.js and .wasm files contain the packages, so no runtime installation is needed. This is the most robust offline strategy but requires maintaining a forked Pyodide build.

Verification Steps You Can Run Today

1. Open the browser console on a page that loads PyScript and run micropip.install('--help') (or check the micropip source) to confirm no --find-links or --index-url options exist.
2. Inspect the <py-config> TypeScript definitions (@types/pyscript or the PyScript repo) for any offline, vendor, or lockfile properties—none are present in the 2024‑2025 releases.

One Diagnostic Detail That Changes the Recommendation

Do you control the PyScript/Pyodide build pipeline, or must you use the official CDN releases? If you can build a custom Pyodide, option 3 (pre‑baked distribution) is the only fully supported offline path. If you are locked to the CDN, you must use the unofficial workarounds above and accept the maintenance burden.