Why does an old library still call a removed function?

huggingface_hub is a shared dependency that many libraries (sentence-transformers, transformers, diffusers, datasets) import directly rather than wrapping. When huggingface_hub ships a breaking release, every library that pins a loose or old version range for it can break simultaneously, even though you didn't touch that library's own version. This is why the traceback often points into a library you didn't upgrade yourself.

What about 'cannot import name HfFolder from huggingface_hub'?

Same root cause, different symbol. HfFolder was replaced by explicit token handling: pass token="hf_..." directly to functions like from_pretrained() or hf_hub_download(), or use huggingface_hub.login() once per session instead of managing the folder-based token cache manually.

Is use_auth_token deprecated too?

Yes. use_auth_token was renamed to token across the Hugging Face ecosystem. Passing use_auth_token still works in many current versions but prints a FutureWarning, and it will eventually be removed the same way cached_download was. Search-and-replace use_auth_token= with token= in your code now rather than waiting for it to become a hard error.

Fix "cannot import name 'cached_download'" from huggingface_hub

huggingface_hub ImportError: cached_download, HfFolder, and the token rename

Q: How do I fix 'ImportError: cannot import name cached_download from huggingface_hub'?

This means huggingface_hub was upgraded to a version that removed cached_download, but something you installed (often an older sentence-transformers, or a pinned requirements.txt) still calls it internally. The fastest fix is pinning huggingface_hub to a compatible version: pip install "huggingface_hub<0.26". The correct long-term fix is upgrading the calling library to a version that uses hf_hub_download instead, since cached_download is gone for good, not just renamed.

huggingface_hub is the low-level client that transformers, sentence-transformers, diffusers, and datasets all use to actually talk to the Hub — download files, resolve revisions, handle auth. It's also had more breaking API churn than any of the libraries built on top of it, which means upgrading one package in a fresh pip install can quietly break three others that pin it loosely. This post covers the three symbols that get removed most often and show up in unrelated stack traces.

pip install huggingface_hub

"cannot import name 'cached_download' from 'huggingface_hub'"

This is the most common one, and it almost never comes from your own code — it shows up when an older sentence-transformers version (or any library that still calls the old download API) runs against a newer huggingface_hub that removed it.

from sentence_transformers import SentenceTransformer
model = SentenceTransformer("all-MiniLM-L6-v2")

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

The traceback points at sentence_transformers, but the actual break is one layer down. Two real fixes, pick based on which library you can afford to touch:

# Option 1: pin huggingface_hub back to a version that still has cached_download
# (fast, works immediately, doesn't fix the underlying staleness)

pip install "huggingface_hub<0.26"

# Option 2: upgrade the library that's calling the removed function
pip install --upgrade sentence-transformers

Option 2 is the correct fix if you can take it — current sentence-transformers releases call hf_hub_download(), the function cached_download was replaced by, so upgrading removes the dependency on the old API entirely. Option 1 is the right call when you're stuck on an old library version for compatibility reasons elsewhere in the same environment and just need things working today.

"cannot import name 'HfFolder' from 'huggingface_hub'"

Same shape of error, different removed symbol. HfFolder used to manage a token cached on disk (~/.huggingface/token); it's been replaced by passing the token explicitly or logging in once per session.

# Old pattern, now breaks:
from huggingface_hub import HfFolder
HfFolder.save_token("hf_xxx")

# Current pattern — pass the token directly where you need it
from transformers import AutoModel
model = AutoModel.from_pretrained("bert-base-uncased", token="hf_xxx")

# Or log in once for the whole session (writes to the same cache location
# HfFolder used to manage, just via a supported API)
from huggingface_hub import login
login(token="hf_xxx")

If you're setting the token via an environment variable instead, nothing changes — HF_TOKEN is still read automatically by every current Hub-aware function, and that path was never affected by this removal.

The use_auth_token → token rename

This one doesn't throw yet, which is exactly why it's worth fixing before it does:

FutureWarning: `use_auth_token` is deprecated and will be removed in a future version of
huggingface_hub. Please use `token` instead.

# Deprecated, still works today
model = AutoModel.from_pretrained("private-org/private-model", use_auth_token="hf_xxx")

# Correct
model = AutoModel.from_pretrained("private-org/private-model", token="hf_xxx")

This follows the exact same lifecycle cached_download went through: deprecation warning first, then a version or two later, a hard TypeError or ImportError. If you have use_auth_token= anywhere in a codebase you maintain, treat the warning as a to-do, not noise — a global search-and-replace to token= now is cheaper than debugging the eventual break in production.

Pinning versus upgrading: which to reach for

All three of the errors above trace back to the same trade-off. Pinning huggingface_hub to an older, compatible version is the fastest way to unblock a broken environment right now:

pip install "huggingface_hub==0.25.2"

But it's a stopgap, not a fix — you're now holding back a shared dependency that other packages in the same environment may want a newer version of, which just moves the conflict somewhere else. The durable fix is always upgrading whichever specific library is calling the removed symbol, since that's the thing actually out of date. Reach for the pin when you need something working in the next five minutes; reach for the upgrade when you have time to verify nothing else in the environment depends on the old behavior.

Error Fix

Fix HuggingFace Tokenizer Padding Errors

Error Fix

Fix HuggingFace Model Loading Out-of-Memory Errors

Error Fix

Fix HuggingFace Cache "No Space Left on Device"

huggingface_hub ImportError: cached_download, HfFolder, and the token rename

"cannot import name 'cached_download' from 'huggingface_hub'"

"cannot import name 'HfFolder' from 'huggingface_hub'"

The use_auth_token → token rename

Pinning versus upgrading: which to reach for

Related articles