Make HF_HUB_ENABLE_HF_TRANSFER deprecation warning visible to users#4220
Conversation
- constants.py: always warn when the legacy env var is set (not only when HF_XET_HIGH_PERFORMANCE is also set), and use FutureWarning instead of DeprecationWarning so the message reaches end users (DeprecationWarning is silenced by default under standard `python` execution). - upload.md: add an explicit TIP under "Upload from the CLI" pointing users to HF_XET_HIGH_PERFORMANCE=1 for max throughput, and noting that the legacy HF_HUB_ENABLE_HF_TRANSFER=1 flag is no longer effective. Closes huggingface#4219
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit c807aab. Configure here.
Cursor Bugbot correctly flagged that the previous commit's guard removal was based on inverted boolean reading. The original `and not HF_XET_HIGH_PERFORMANCE` already fires the warning in the common case (legacy flag set, new flag not set) and correctly suppresses it for users who have already migrated to HF_XET_HIGH_PERFORMANCE=1 but still have the legacy var lingering in their environment. The real visibility fix is the DeprecationWarning -> FutureWarning change, which is preserved. Restoring the guard avoids unnecessary warning noise for already-migrated users.
hanouticelina
left a comment
There was a problem hiding this comment.
Hi @Adithya191101,
HF_HUB_ENABLE_HF_TRANSFER is already ignored in all 1.x versions since hf-xet became the default upload backend, so setting it does nothing, which is why you saw no speedup. the deprecation is also already covered in the env vars doc. I'm still okay adding a tip in the upload docs.
I'm also okay with the DeprecationWarning --> FutureWarning change, dfeprecationWarning raised from a library module is silenced by Python's default filter, which is exactly why you didn't see it.
|
The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #4220 +/- ##
==========================================
+ Coverage 75.00% 77.08% +2.08%
==========================================
Files 145 171 +26
Lines 13978 19485 +5507
==========================================
+ Hits 10484 15020 +4536
- Misses 3494 4465 +971 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
This PR has been shipped as part of the v1.15.0 release. |
What this changes
Closes #4219.
Two small changes so users with the legacy
HF_HUB_ENABLE_HF_TRANSFER=1env variable actually learn about its deprecation and the replacement flag.src/huggingface_hub/constants.pyChanged
DeprecationWarning→FutureWarning. Python silencesDeprecationWarningby default in user-facing code, so end users runninghf upload …from the CLI never saw the deprecation message even though the warning was being raised.FutureWarningis shown by default and matches the intent (alert the user that their current configuration is no longer effective). This also matches the existing convention in this package — the otherwarnings.warn(...)calls undersrc/huggingface_hub/useFutureWarning.docs/source/en/guides/upload.mdAdded a TIP callout in the Upload from the CLI section pointing users to
HF_XET_HIGH_PERFORMANCE=1for max throughput, and explicitly noting that the legacyHF_HUB_ENABLE_HF_TRANSFER=1flag is no longer effective. Currently this guidance is buried in the "Tips and tricks for large uploads" sub-section, which most users following the basic CLI quickstart never reach.Why
Discovered while uploading a 7.7 GB safetensors file from a residential WiFi connection — set
HF_HUB_ENABLE_HF_TRANSFER=1per multiple older tutorials, saw no speedup, never saw any warning. After a lot of digging realized the warning was being raised but silently filtered by Python's defaultDeprecationWarningbehavior. The forum has a long thread (https://discuss.huggingface.co/t/upload-speeds-extremely-slow-stalling-since-april-1st/174910) of users hitting the same confusion and being directed toHF_HUB_DISABLE_XET=1workarounds rather than the documentedHF_XET_HIGH_PERFORMANCE=1path.Test plan
python -c "import ast; ast.parse(open('src/huggingface_hub/constants.py').read())"parses cleanly.[!TIP]callouts indocs/source/en/guides/upload.mduse the same syntax as the new one.HF_HUB_ENABLE_HF_TRANSFER=1(withoutHF_XET_HIGH_PERFORMANCE) and importinghuggingface_hubnow emits a visibleFutureWarning(manually verified).HF_HUB_ENABLE_HF_TRANSFER=1andHF_XET_HIGH_PERFORMANCE=1correctly suppresses the warning for already-migrated users.make style/make qualityandpytest testsbefore merge if maintainers want — happy to push fixups.Note
Low Risk
Low risk: only updates user-facing documentation and changes a warning class from
DeprecationWarningtoFutureWarningwithout affecting upload logic or API behavior.Overview
Clarifies CLI upload guidance by adding a TIP recommending
HF_XET_HIGH_PERFORMANCE=1for maximum throughput and explicitly notingHF_HUB_ENABLE_HF_TRANSFERis no longer effective.Updates the legacy
HF_HUB_ENABLE_HF_TRANSFERdeprecation notice inconstants.pyto emit a user-visibleFutureWarning(instead of a typically-silencedDeprecationWarning).Reviewed by Cursor Bugbot for commit 936145d. Bugbot is set up for automated code reviews on this repo. Configure here.