Fix "cannot import name 'is_offline_mode'" and other huggingface_hub ImportErrors
cannot import name 'is_offline_mode' from 'huggingface_hub': the hub is too old for your transformers. transformers 5.x imports it, and it exists only from huggingface_hub 1.2.1. Fix:pip install -U "huggingface_hub>=1.5,<2"(the range transformers 5.17.0 declares).cannot import name 'cached_download': the hub is too new for an old library. Removed in 0.26.0. Fix:pip install -U sentence-transformers. Pinninghuggingface_hub<0.26alone now fails, because transformers 4.57.6 needs 0.34 or newer.cannot import name 'HfFolder': removed in 1.0.0. Useget_token()andlogin().use_auth_token: aTypeErrorinhf_hub_downloadfrom 1.0.0. Rename it totoken=.
huggingface_hub is the low-level client that transformers, sentence-transformers, diffusers and datasets all use to download files, resolve revisions and handle auth. Its API has moved a lot between releases, and the direction of the mismatch matters: some of these errors mean the hub is too new for the calling library, one means it is too old. Read the missing name first, then pick the fix.
Reproduced
Every row below was run in a fresh venv. Removal and addition versions were found by installing neighbouring releases and checking hasattr(huggingface_hub, name) on each.
| What I ran | Exact result | Fix that worked |
|---|---|---|
transformers 5.17.0 + huggingface_hub 0.36.2, import transformers | ImportError: cannot import name 'is_offline_mode' from 'huggingface_hub' | pip install -U "huggingface_hub>=1.5,<2" (got 1.33.0) |
| sentence-transformers 2.2.2 (pulled transformers 4.57.6, huggingface_hub 0.36.2) | ImportError: cannot import name 'cached_download' from 'huggingface_hub' (...). Did you mean: 'hf_hub_download'? | pip install -U sentence-transformers (got 6.1.0, transformers 5.17.0, hub 1.33.0) |
Same env, pip install "huggingface_hub<0.26" | ImportError: huggingface-hub>=0.34.0,<1.0 is required for a normal functioning of this module, but found huggingface-hub==0.25.2. | Also pin "transformers<4.45" (got 4.44.2 + hub 0.25.2, imports OK) |
from huggingface_hub import HfFolder on 1.33.0 | ImportError: cannot import name 'HfFolder' from 'huggingface_hub' | from huggingface_hub import get_token, login |
hf_hub_download(..., use_auth_token=False) on 1.0.0 and 1.33.0 | TypeError: hf_hub_download() got an unexpected keyword argument 'use_auth_token' | token= |
| transformers 5.17.0 + huggingface_hub 2.0.0 | ImportError: huggingface-hub>=1.5.0,<2.0 is required for a normal functioning of this module, but found huggingface-hub==2.0.0. | Go back under 2.0: "huggingface_hub>=1.5,<2" |
| transformers 4.57.6 + huggingface_hub 1.33.0 | ImportError: huggingface-hub>=0.34.0,<1.0 is required for a normal functioning of this module, but found huggingface-hub==1.33.0. | Upgrade transformers to 5.x, or pin "huggingface_hub<1.0" |
| Name | Last version that has it | First version without it |
|---|---|---|
cached_download | 0.25.2 | 0.26.0 (removed) |
HfFolder | 0.36.2 | 1.0.0 (removed) |
use_auth_token= in hf_hub_download | 0.36.2 | 1.0.0 (TypeError) |
is_offline_mode (added, not removed) | absent in 1.0.0, 1.1.7, 1.2.0 | present from 1.2.1 |
"cannot import name 'is_offline_mode' from 'huggingface_hub'"
This one is the reverse of the others. Nothing was removed: transformers 5.x moved to importing is_offline_mode from huggingface_hub, and your installed hub predates it. In transformers 4.57.6 the function was defined locally in transformers/utils/hub.py (it read huggingface_hub.constants.HF_HUB_OFFLINE). In 5.0.0 and later the same file does from huggingface_hub import (..., is_offline_mode, ...), and that file loads on plain import transformers:
File ".../transformers/utils/hub.py", line 30, in <module>
from huggingface_hub import (
ImportError: cannot import name 'is_offline_mode' from 'huggingface_hub' (.../huggingface_hub/__init__.py)
pip normally prevents this combination. transformers 5.0.0 declares huggingface-hub>=1.3.0,<2.0 and 5.17.0 declares >=1.5.0,<2.0. You get here when something installs an old hub afterwards, such as a requirements.txt line like huggingface_hub==0.36.2. pip prints the warning and installs it anyway:
transformers 5.17.0 requires huggingface-hub<2.0,>=1.5.0, but you have huggingface-hub 0.36.2 which is incompatible.
pip install -U "huggingface_hub>=1.5,<2"
pip check # confirms nothing else in the env still wants the old hubIf another package in the same env really needs huggingface_hub<1.0, you cannot satisfy both. Either upgrade that package or keep transformers on 4.x (pip install "transformers<5"; 4.57.6 declares huggingface-hub>=0.34.0,<1.0). Do not jump to huggingface_hub 2.0.0 either: transformers 5.17.0 refuses it at import time (row 6 above).
If your own code needs the offline flag, both of these worked on 1.33.0 with HF_HUB_OFFLINE=1 set (both returned True). The second one also works on 0.x hubs:
from huggingface_hub import is_offline_mode # 1.2.1 and newer
is_offline_mode()
from huggingface_hub import constants # 0.x and 1.x
constants.HF_HUB_OFFLINE
"cannot import name 'cached_download' from 'huggingface_hub'"
This almost never comes from your own code. sentence-transformers 2.2.2 imports it at the top of SentenceTransformer.py, so the import fails before any model loads:
from sentence_transformers import SentenceTransformer
File ".../sentence_transformers/SentenceTransformer.py", line 12, in <module>
from huggingface_hub import HfApi, HfFolder, Repository, hf_hub_url, cached_download
ImportError: cannot import name 'cached_download' from 'huggingface_hub' (.../huggingface_hub/__init__.py). Did you mean: 'hf_hub_download'?
Installing sentence-transformers==2.2.2 today pulls transformers 4.57.6 and huggingface_hub 0.36.2, so the break happens on a clean install, not only after an upgrade. The traceback points at sentence_transformers, but the missing name belongs to the hub.
# Fix 1 (worked): upgrade the library that calls the removed function
pip install -U sentence-transformersThat gave sentence-transformers 6.1.0, transformers 5.17.0 and huggingface_hub 1.33.0, and the import succeeded. Current releases use hf_hub_download(), which is the replacement Python itself suggests in the error.
# Fix 2 (only if you must stay on the old library): pin both packages
pip install "huggingface_hub<0.26" "transformers<4.45"Pinning only huggingface_hub<0.26 is common advice and it no longer works on its own. It installed 0.25.2, and then transformers 4.57.6 refused to import with huggingface-hub>=0.34.0,<1.0 is required. Adding transformers<4.45 resolved to 4.44.2 with hub 0.25.2, and from sentence_transformers import SentenceTransformer worked. Treat that as a frozen legacy env, not a place to add new packages.
If your own code calls cached_download(url), switch to hf_hub_download(repo_id=..., filename=...). It takes a repo and a filename instead of a URL.
"cannot import name 'HfFolder' from 'huggingface_hub'"
HfFolder still imports in 0.36.2 and is gone in 1.0.0. It managed a token cached on disk. The replacements:
# Old, fails on huggingface_hub 1.x:
from huggingface_hub import HfFolder
HfFolder.save_token("hf_xxx")
token = HfFolder.get_token()
# Current:
from huggingface_hub import login, get_token
login(token="hf_xxx") # once per machine or session
token = get_token() # returns None when no token is configured
Or skip the cache entirely and pass the token where you need it:
from transformers import AutoModel
model = AutoModel.from_pretrained("private-org/private-model", token="hf_xxx")
Setting HF_TOKEN as an environment variable is still read automatically, and was not affected by this removal.
use_auth_token: a TypeError in the hub, silently unused in transformers
On huggingface_hub 0.36.2, hf_hub_download(..., use_auth_token=False) still ran, and it printed no warning in my run even with all warnings enabled. From 1.0.0 it is a hard error:
TypeError: hf_hub_download() got an unexpected keyword argument 'use_auth_token'
transformers 5.17.0 behaves differently. AutoConfig.from_pretrained("openai-community/gpt2", use_auth_token=False) loaded the config with no error, but use_auth_token does not appear anywhere in the transformers 5.17.0 source, so nothing reads it as a token. On a private repo that means an auth failure that does not mention the argument at all. Rename it everywhere:
# Old
model = AutoModel.from_pretrained("private-org/private-model", use_auth_token="hf_xxx")
# Current
model = AutoModel.from_pretrained("private-org/private-model", token="hf_xxx")
Pin or upgrade?
Use the missing name to decide which side is out of date:
is_offline_modemissing: the hub is too old. Upgrade huggingface_hub within the range your transformers declares.cached_download,HfFolder, or ause_auth_tokenTypeError: the hub is newer than the calling library. Upgrade that library.- A message like
huggingface-hub>=X,<Y is required for a normal functioning of this module: transformers checked the version for you. Install inside that range.
After any change, run pip check. In every broken env above, pip had already printed the conflict at install time.