# Fix "ImportError: cannot import name 'cached_download' from 'huggingface_hub'"

Yes. An agent replaces hf_hub_url plus cached_download with hf_hub_download, fixes the imports that broke beside it, and proves the package imports before a PR.

[Run this on Rush](https://cloud.getrush.ai/run/fix-cannot-import-name-cached-download/huggingface-hub/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

`cached_download` was the old two-step way to fetch a file from the Hub: build a URL with `hf_hub_url`, then download it. huggingface_hub 0.25.2 still exports it; 0.26.0 does not, and the current 2.4.0 release answers `from huggingface_hub import cached_download` with `ImportError: cannot import name 'cached_download' from 'huggingface_hub'`. A requirements line like `huggingface-hub>=0.10.0` resolves to the newest release on every clean install, so a project that worked for years breaks on the next fresh environment, usually at import time, before any model is loaded.

shahules786/mayavoz, a PyTorch Lightning toolkit for speech enhancement, is a typical case. `requirements.txt` lists `huggingface-hub>=0.10.0`, `pytorch-lightning>=1.7.7` and `torch>=1.12.1` with no upper bounds. `mayavoz/models/model.py` imports `cached_download, hf_hub_url` on line 11 and `pytorch_lightning.utilities.cloud_io.load` on line 12, and `Mayamodel.from_pretrained` on lines 316 to 325 builds the URL for `pytorch_model.ckpt` with `hf_hub_url(model_id, filename=..., revision=...)` and fetches it with `cached_download(url=url, library_name="mayavoz", library_version=__version__, cache_dir=..., use_auth_token=...)`. The package's `__init__.py` imports that module, so `import mayavoz` itself fails. The CI workflow in `.github/workflows/ci.yaml` tests on Python 3.8 only, which is why nothing caught the drift.

The agent installs the requirements fresh and finds that the import fails three times, in order. First, `mayavoz/__init__.py` line 1 calls `__import__("pkg_resources").declare_namespace(__name__)`, and setuptools 82.0.0 removed `pkg_resources`, so the current setuptools answers `ModuleNotFoundError: No module named 'pkg_resources'`; with setuptools 81 pinned the line passes. Second, line 11 of `model.py` raises the error in the title. Third, `pytorch_lightning.utilities.cloud_io` is gone in Lightning 2.0.9 and later, though 1.9.5 still has it. Each one is reproduced in the run with the exact version that fails and the last version that works, so the pull request can say which pins would have held and why the port is better.

Then it ports the loader. `hf_hub_url` plus `cached_download` becomes one call, `hf_hub_download(repo_id=model_id, filename=HF_TORCH_WEIGHTS, revision=revision_id, library_name="mayavoz", library_version=__version__, cache_dir=cached_dir, token=use_auth_token)`, which returns the same local path and keeps the `@revision` syntax the method already parses. `pl_load` was a wrapper around `torch.load`, so the checkpoint is read with `torch.load(path, map_location=map_location)`; the agent keeps the same `map_location` and reads the installed `torch.load` signature for the `weights_only` default before choosing how to call it. The namespace declaration is deleted, since the package has no second distribution to share the name with. It adds lower bounds that match what it tested, and writes a test that calls `from_pretrained` on a checkpoint it saves locally in the test, so no Hub download is needed to prove the loader.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "A fresh install of this Python package fails at import with ImportError: cannot import name 'cached_download' from 'huggingface_hub'. Read the dependency files and the package's import chain, and report which huggingface_hub, torch, pytorch_lightning and setuptools versions a clean install resolves to and which lines fail. Reproduce it in a clean virtual environment: install the requirements, import the package, and record every import-time error in the order they appear, fixing each only far enough to reach the next, so the pull request lists all of them. For each failing import, find the last version of that dependency that still worked and say so. Then port the code: replace hf_hub_url plus cached_download with a single hf_hub_download call that keeps the same repo id, filename, revision, cache directory, token and library name; replace removed Lightning helpers with the torch call they wrapped, keeping map_location; remove pkg_resources namespace declarations the package does not need. Set lower bounds on the dependencies you tested. Write a test that saves a small checkpoint locally and loads it through the public from_pretrained path without any network access, run the existing tests that need no data, and include the output. Do not download models from the Hub. Open a pull request that lists each changed line, the versions installed, and what could not be verified offline.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that changes the model loader, the package's `__init__.py` and the requirements file, and adds one test. Its description opens with the three import errors in the order a fresh environment hits them, each with the dependency release that introduced it and the last release that still worked, so a reviewer can see at a glance that pinning would have needed three pins and bought only time.

The diff is a few lines per file. A reviewer checks that the `hf_hub_download` call carries every argument the old pair did, especially `revision` and the token, since a missing revision silently loads the latest checkpoint instead of the pinned one; that the `torch.load` call keeps `map_location` and makes a deliberate choice about `weights_only`; and that the new test really exercises `from_pretrained` rather than a helper around it.

What the run cannot prove is listed last. No model was fetched from the Hub, so the first real `from_pretrained("<org>/<model>")` with a network connection is for the reviewer, as is a full training run on the GPU the project targets.

## Run it on every Monday morning

A dependency with no upper bound breaks on its own schedule, and a project whose CI runs only on pushes finds out from a user. Give the repository's Project an automation with the prompt above and a `schedule` trigger with a weekly `cron` in your `timezone`. Each run installs the requirements fresh, imports the package and runs the offline tests; it opens a pull request only when something fails, so a quiet week costs one run and no review.

If the first sign is still a report from a user, a Linear issue labelled `install-broken` can start the same automation through a `linear` trigger on `linear.issue.labeled`; the issue's text is added after the prompt, and the trigger needs a Linear connection on the account that owns the automation, made in the console under Settings → Connections.

## Why run it on Rush?

The error is one import, but the fix is only safe once every other import-time break is known, and a laptop with a two-year-old environment hides all of them. The agent works in a sandbox with nothing installed, so what it sees is what a new user sees: it installs the requirements as written, records each failure, pins back one dependency at a time to find where each break started, and keeps every command and its output in the session.

Proof for a model loader is awkward because the obvious test downloads a checkpoint. The agent sidesteps that: it saves a small checkpoint in the test itself and loads it through the same public method, so the pull request shows the loader working with no network and no credentials, and the description says plainly that the first Hub download is still for the reviewer.

## Frequently asked questions

### Can I pin huggingface_hub below 0.26 instead?

It restores `cached_download`, and the run shows 0.25.2 still exports it. But the same fresh install also failed on `pkg_resources` and on a Lightning import, so the pin fixes one of three breaks, and every library that depends on huggingface_hub will eventually require a release past it.

### What replaces hf_hub_url plus cached_download?

A single `hf_hub_download(repo_id=..., filename=..., revision=...)` call. It takes the same `cache_dir`, `library_name` and `library_version`, takes `token` where the old call took `use_auth_token`, and returns the local path, so the caller's code after the download is unchanged.

### Why does import also fail on pkg_resources?

setuptools 82.0.0 removed the `pkg_resources` module. A package that declares a namespace with `__import__("pkg_resources").declare_namespace(__name__)` fails before any of its own code runs. If the name is not shared with another distribution, deleting the line is the whole fix.

### Does the agent download a model from the Hub?

No. The request forbids it. The loader is proven with a checkpoint the test writes locally, which covers the file read and the `map_location` handling. The first real download, and the quality of the enhanced audio, are for you to check.

### Will it also move the project to the lightning package?

Not in this run. It replaces the one removed helper with the `torch.load` call it wrapped and leaves `pytorch_lightning` imports elsewhere alone. Moving to the `lightning` package is a wider change and belongs in its own pull request.

## More jobs like this: Fix a bug from an alert

- [Fix "ImportError: cannot import name 'ChatOpenAI' from 'langchain.chat_models'" in LangChain 1.0](https://getrush.ai/run/fix-cannot-import-name-chatopenai-from-langchain-chat-models/langchain/)
- [Fix "ImportError: cannot import name 'compare_ssim' from 'skimage.measure'"](https://getrush.ai/run/fix-cannot-import-name-compare-ssim-from-skimage-measure/scikit-image/)
- [Fix "ImportError: cannot import name 'executor' from 'aiogram'" in a Telegram bot](https://getrush.ai/run/fix-cannot-import-name-executor-from-aiogram/aiogram/)
- [Fix ImportError: Cannot Import Name 'json' From 'itsdangerous' in a Flask 1 App](https://getrush.ai/run/fix-cannot-import-name-json-from-itsdangerous/itsdangerous/)
- [Fix "ImportError: cannot import name 'mock_s3' from 'moto'" in a pytest suite](https://getrush.ai/run/fix-cannot-import-name-mock-s3-from-moto/moto/)
- [Fix "ImportError: cannot import name 'plot_confusion_matrix' from 'sklearn.metrics'"](https://getrush.ai/run/fix-cannot-import-name-plot-confusion-matrix-from-sklearn-metrics/scikit-learn/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
