I think it’s better to wait for the infrastructure side to make the fix. @hysts
Gradio-Lite is breaking on Spaces because Pyodide’s package installer (micropip) can only install pure-Python or Pyodide-built wheels. Recent dependency resolution pulls a huggingface-hub requirement that micropip refuses to install, so the app never boots. The failing traceback and version range (huggingface-hub<1.0,>=0.33.5) are shown in your forum post.
What’s going on (short, then detailed)
- Short. Lite runs Python in the browser via Pyodide. Packages get fetched at runtime with
micropip. If any transitive dep lacks a pure-Python wheel, install halts and Lite fails. That’s what you’re hitting. (Pyodide)
- Detailed. Pyodide accepts: (1) pure-Python wheels from PyPI and (2) wheels Pyodide prebuilt for WebAssembly. Anything else errors as “Can’t find a pure Python 3 wheel …”. This is by design. If a maintainer changes deps or publishes a version without a pure wheel, working Lite apps can break on rebuild. (Pyodide)
Fresh signals that match your failure
- New GitHub issue reproducing that Lite boot failure with the same error text and stack. (GitHub)
- Prior Lite breakages from dependency drift, e.g.,
pydantic mismatches under specific Pyodide versions. (GitHub)
- Other Lite-context failures that aren’t wheels but still bite browser mode (e.g., WebSocket timeouts). These confirm “works locally, fails in Lite” is common when browser constraints apply. (GitHub)
Root causes to watch for
- Non-pure or missing wheels.
micropip only installs pure-Python or Pyodide wheels. If resolution lands on any package without such a wheel, install fails. Error message is exactly what you saw. (Pyodide)
- Dependency churn. A new lib or sub-dep can flip from “pure” to “needs native” or change constraints. Even small changes (e.g.,
pydantic switching lines) have broken Lite in the past. (GitHub)
- Pyodide version mismatch. Older Lite embeds an older Pyodide. If your deps assume a newer baseline, import or wheel resolution breaks. (Pyodide)
Workarounds and fixes (ranked, least to most risk)
A. Avoid Python-side Hub calls inside Lite. Use JS clients.
Replace huggingface_hub in Python with JS APIs so micropip installs nothing. Use @huggingface/inference or @huggingface/hub from JS, or run models in-browser with Transformers.js. This sidesteps Python wheels entirely. (Hugging Face)
<!-- Use HF JS in the page; no Python deps -->
<script type="module">
// @huggingface/inference docs: https://huggingface.co/docs/huggingface.js/en/inference/README
import { HfInference } from "https://cdn.skypack.dev/@huggingface/inference";
const hf = new HfInference("hf_xxx"); // supply token if model requires it
// Example: text generation
const out = await hf.textGeneration({ model: "meta-llama/Llama-3.1-8B-Instruct", inputs: "Hello" });
console.log(out.generated_text);
</script>
B. If you want Python UI + in-browser models, use transformers-js via the official wrapper.
Install only the tiny Python wrapper transformers-js-py; the heavy lifting happens in JS. This pattern is the Gradio-recommended Lite path. (gradio.app)
<!-- Gradio-Lite + Transformers.js.py keeps deps Lite-safe -->
<script type="module" crossorigin src="https://cdn.jsdelivr.net/npm/@gradio/lite/dist/lite.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gradio/lite/dist/lite.css"/>
<gradio-lite>
import gradio as gr
# transformers-js docs: https://huggingface.co/docs/transformers.js/en/index
# wrapper docs: https://www.gradio.app/4.44.1/guides/gradio-lite-and-transformers-js
from transformers_js_py import pipeline
pipe = await pipeline("sentiment-analysis")
demo = gr.Interface.from_pipeline(pipe)
demo.launch()
<gradio-requirements>
transformers-js-py
</gradio-requirements>
</gradio-lite>
C. Pin or remove problem packages in <gradio-requirements>.
Start from zero. Boot UI. Add one dep at a time. If adding huggingface_hub breaks, delete it and call the Hub from JS instead. If you must keep it, try an older known-good pin and test, but expect churn. (gradio.app)
D. Install from a direct wheel URL known to be pure.
micropip can install a specific wheel URL. If PyPI has a pure wheel for a working hub version, point to it explicitly. This can bypass resolver weirdness. (Micropip)
# In your <gradio-lite> Python block
# Micropip URL installs: https://micropip.pyodide.org/en/stable/project/usage.html
import micropip
await micropip.install("https://files.pythonhosted.org/packages/.../huggingface_hub-0.XX.X-py3-none-any.whl")
E. Use keep_going=True once to discover every offender.
Get a complete list of missing wheels instead of failing on the first one. Then eliminate or replace them. (Micropip)
# List all packages without compatible wheels
import micropip
try:
await micropip.install(["your", "deps", "here"], keep_going=True)
except Exception as e:
print(e) # shows all missing/pinned offenders
F. Bump to latest Lite and thus newer Pyodide.
Load the newest @gradio/lite so you inherit a newer Pyodide and wider built-in wheel set. Regression risk exists but often fixes old incompatibilities. (Pyodide)
G. If you truly need Python packages with native code, don’t use Lite.
Move that app to a normal CPU/GPU Space where pip can install platform wheels. Browser Python cannot build or load native extensions. (Pyodide)
Triage checklist you can run today
- Rebuild with an empty
<gradio-requirements> and confirm the UI loads. Then add deps one by one. When it breaks, you found the blocker. (gradio.app)
- If the blocker is
huggingface_hub, remove it and switch to JS clients or Transformers.js for the same task. (Hugging Face)
- If you insist on Python Hub, try an explicit pure wheel URL for a version you’ve verified on PyPI has
py3-none-any.whl. (Pyodide)
- Run once with
keep_going=True to list all missing wheels. Eliminate or replace them. (Micropip)
- Upgrade
@gradio/lite to latest to pick up a newer Pyodide. Re-test. (Pyodide)
- If networking APIs fail in Lite (timeouts/WS), call them from JS or move off Lite. Browser constraints differ from server Python. (GitHub)
Background: why JS routes are the stable path
- JS SDKs (
@huggingface/inference, @huggingface/hub) talk to Hugging Face services directly. No Python, no wheels, no micropip. Stable in browser. (Hugging Face)
- Transformers.js runs models on WebGPU/CPU in the browser. The Gradio team documents the
transformers-js-py bridge specifically to make Lite apps dependency-light. (gradio.app)
References and similar reports
- New GitHub issue: same
huggingface-hub wheel error halts Lite. (GitHub)
- Prior Lite issues:
pydantic versioning under Pyodide; browser-only API timeouts. (GitHub)
- Pyodide docs: pure-Python wheel requirement, package loading rules. (Pyodide)
- Gradio-Lite guides:
<gradio-requirements> usage and Transformers.js patterns. (gradio.app)
Short, curated extras
How Lite works and how to debug
- Gradio-Lite intro and debugging tip (check browser console). Useful when your app shows a blank screen. (Hugging Face)
Pyodide specifics
micropip usage and direct-URL installs. Handy for explicit wheel pins. (Micropip)- Pyodide package list. Check what’s already prebuilt before adding deps. (Pyodide)
Here’s what to do if you were the HF infra team and want to fix the root cause (and stop this class of breakages from recurring).
TL;DR (actionable)
-
Upgrade the Pyodide version used by @gradio/lite on Spaces to ≥ 0.27.6 (prefer latest stable) — 0.27.6 fixes a micropip bug with package names containing dashes, which directly affects huggingface-hub (dash in dist name, underscore in module). The failing threads show Lite running on Pyodide 0.27.3. (Hugging Face Forums)
-
Ship a curated, locked Lite environment:
- Generate and publish a
pyodide-lock.json (via micropip.freeze) for the official Lite template + demo, and load it with Pyodide’s lockFileURL so dependency resolution is frozen and reproducible. (micropip.pyodide.org)
- Add an internal constraints list and alternate index to micropip (supported params) so Spaces can prefer a vetted index/mirror for Lite-only packages. (micropip.pyodide.org)
-
Make Lite defaults avoid Python Hub where possible:
- Update templates/docs to prefer HuggingFace.js or Transformers.js for browser inference and Hub calls; keep Python UI minimal. This sidesteps wheels entirely. (gradio.app)
-
Gate-keep bad deps early:
- Add a preflight “Lite compatibility” check during Space build: run
micropip.install(..., keep_going=True) against the <gradio-requirements> to list all non-installable wheels and fail fast with guidance. (micropip.pyodide.org)
