Learn AI Create the Future — with Pranay
Main site

Error database

ImportError: cannot import name 'cached_download' from 'huggingface_hub'

huggingface_hub removed the old cached_download function, and an outdated library (often sentence-transformers or diffusers) still imports it. Upgrade the importing library.

The message you saw
ImportError: cannot import name 'cached_download' from 'huggingface_hub'

By Updated

The error

Output
ImportError: cannot import name 'cached_download' from 'huggingface_hub' (/usr/lib/python3.11/site-packages/huggingface_hub/__init__.py)

What it means

cached_download was an old download helper in huggingface_hub, deprecated for a long time and removed in release 0.26 (late 2024). Some other library in your environment — the one at the top of the traceback — was written against the old API and still tries to import it. New hub, old consumer: the import fails before any of your code runs.

Why it happens

The Hugging Face ecosystem is a family of separately versioned packages (huggingface_hub, transformers, sentence-transformers, diffusers, datasets) that must roughly match. Installing or upgrading one package pulls the newest huggingface_hub, while an old pinned consumer stays behind. The famous pairing: sentence-transformers==2.2.2 — pinned in countless RAG tutorials — with any current hub.

How to fix it

1. Read the traceback to find the importer. The file path in the first frames names the guilty package. Typically:

Output
File ".../sentence_transformers/SentenceTransformer.py", line 11, in <module>
    from huggingface_hub import HfApi, HfFolder, Repository, hf_hub_url, cached_download

2. Upgrade that package.

bash
pip install -U sentence-transformers

Versions 2.3.0 and later dropped the removed import. The same move applies to old diffusers, datasets or anything else the traceback names.

3. Cannot upgrade the consumer? Pin the hub back — temporarily.

bash
pip install "huggingface_hub==0.25.2"

This restores the old API surface. It is a stopgap: an old hub will eventually conflict with new transformers and new model repo layouts. Note the pin with a comment and remove it when the consumer updates.

4. Check the pair explicitly when in doubt.

bash
pip show huggingface_hub sentence-transformers

Hub at 0.26+ demands sentence-transformers at 2.3+; any older consumer needs fix 2 or fix 3.

How to prevent it

Upgrade Hugging Face packages as a set, not one at a time. When copying a tutorial's pinned requirements, check the pins' age — a sentence-transformers==2.2.2 from 2023 is a known landmine. A lock file (pip-tools, uv, poetry) keeps the family consistent per project.