ImportError on `import gradio` with current PyPI: huggingface_hub 1.x removed HfFolder

Summary

Fresh installs from requirements-app.txt are currently broken: import gradio raises ImportError: cannot import name 'HfFolder' from 'huggingface_hub' before app.py runs. The fix is one upper-bound pin in requirements-app.txt.

Reproducer

git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.git
cd HivisionIDPhotos
git checkout v1.3.1
python3.12 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt -r requirements-app.txt
python app.py --host 127.0.0.1 --port 7860

Result:

File "<...>/.venv/lib/python3.12/site-packages/gradio/oauth.py", line 13, in <module>
    from huggingface_hub import HfFolder, whoami
ImportError: cannot import name 'HfFolder' from 'huggingface_hub'

Root cause

gradio/oauth.py in 4.x imports HfFolder at module top level, so import gradio triggers the chain and fails.

Verified:

• huggingface_hub 0.36.2 (latest 0.x): exports HfFolder (4 references in __init__.py)
• huggingface_hub 1.0.0+: HfFolder removed
• gradio 4.44.1's oauth.py: from huggingface_hub import HfFolder, whoami (and uses HfFolder.get_token())

Suggested fix

Add one line to requirements-app.txt:

 gradio>=4.43.0
+huggingface_hub<1
 fastapi

<1 resolves to the highest 0.x (currently 0.36.2). The 0→1 boundary is the canonical breaking-change line in huggingface_hub, so this stays valid through 0.x security patches without freezing to a specific version.

This is a workaround until the gradio 5 upgrade tracked in #187 lands, at which point the right fix is to drop the upper bound on huggingface_hub once gradio 5 imports it correctly.

Related

• #187 — "upgrade to gradio 5.0" (long-term fix; this issue is the short-term unblock for current installs)

Context

Surfaced while authoring an OS8 App Store catalog manifest for HivisionIDPhotos. We've worked around it on our side by pinning both gradio<5 and huggingface_hub<1 in our manifest's postInstall, but anyone installing from requirements-app.txt directly is currently blocked at import gradio.

Happy to send a PR if it'd be useful.