All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Fix a bug from an alert.

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

Keep reading