Add troubleshooting section for hf_transfer installation #272
Conversation
Add collapsible troubleshooting section in installation guide to help users resolve hf_transfer errors when using uv tool install. Users can now easily find the solution to install with --with hf_transfer flag for faster downloads.
WalkthroughTwo troubleshooting sections are added to README.md to address Hugging Face transfer download errors, explaining the issue and providing installation instructions for the Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🔇 Additional comments (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
anthonywu
left a comment
anthonywu
left a comment
There was a problem hiding this comment.
My suggestion here is to just include it in the library instead of expecting users to come back to a readme.
If you're interested in making this change, just update this PR. Otherwise we'll just do this at the next release.
README.md
Outdated
| If you encounter a `ValueError: Fast download using 'hf_transfer' is enabled (HF_HUB_ENABLE_HF_TRANSFER=1) but 'hf_transfer' package is not available`, you can install MFLUX with the `hf_transfer` package included: | ||
|
|
||
| ```sh | ||
| uv tool install --upgrade mflux --with hf_transfer |
There was a problem hiding this comment.
I think an even more durable solution is just to include it in the project dependencies in pyproject.toml
https://pypi.org/project/hf-transfer/#history
hf-transfer>=0.1.9,<1.0 in this list: https://github.com/filipstrand/mflux/blob/main/pyproject.toml#L28
The library has been out for a while and it's maintained by HuggingFace so I feel comfortable just including it as a universal dependency
There was a problem hiding this comment.
Thanks for the review!
My main hesitation was that I wasn’t entirely sure why transformers itself doesn’t include hf-transfer as a direct dependency, so I kept the previous behavior to avoid unintended issues. But given that we mostly target macOS, I agree that adding hf-transfer directly should be fine and unlikely to cause any problems.
I’ve updated the PR accordingly. Thanks again!
- **Root cause**
- Users with HF_HUB_ENABLE_HF_TRANSFER=1 encountered ValueError
because hf_transfer package was not installed by default
- **What was done**
- Added hf-transfer>=0.1.9,<1.0 to project dependencies
- Removed troubleshooting section from README (no longer needed)
- **Verification**
- Package maintained by HuggingFace with stable release history
- Enables faster model downloads automatically for all users
anthonywu
left a comment
anthonywu
left a comment
There was a problem hiding this comment.
cc @filipstrand this looks safe to release next time you bump version
2 participants
I discovered this project yesterday and encountered some issues during installation due to unfamiliarity with
uv.When running
uv tool install --upgrade mfluxandmflux-generate --model schnell --prompt "Luxury food photograph" --steps 2 --seed 2 -q 8, I got the following error:ValueError: Fast download using 'hf_transfer' is enabled (HF_HUB_ENABLE_HF_TRANSFER=1) but 'hf_transfer' package is not available in your environment. Try pip install hf_transfer.For users who prefer not to manually set environment variables or are new to
uv, this can be confusing and prevents the installation from being truly "out-of-the-box."So I added a collapsible troubleshooting section under the installation guide.
Summary by CodeRabbit