Silent deprecation: HF_HUB_ENABLE_HF_TRANSFER=1 no-op for uploads, no warning unless HF_XET_HIGH_PERFORMANCE also set

[Adithya191101]

Describe the bug

HF_HUB_ENABLE_HF_TRANSFER=1 is a silent no-op on the upload code path in huggingface_hub ≥ 1.x — hf_transfer was fully removed in favor of hf-xet. The deprecation warning that exists in constants.py only fires when the user also sets HF_XET_HIGH_PERFORMANCE=1, which doesn't match the actual user journey: most affected users only set the legacy flag (because that's what every older tutorial / Stack Overflow answer / older HF doc still recommends), and so they never see the warning. They assume the flag is doing something, see no speedup, and end up on the forum thinking Xet is broken.

The relevant code in src/huggingface_hub/constants.py:

# hf_transfer is not used anymore. Let's warn user is case they set the env variable
if _is_true(os.environ.get("HF_HUB_ENABLE_HF_TRANSFER")) and not HF_XET_HIGH_PERFORMANCE:
    "The `HF_HUB_ENABLE_HF_TRANSFER` environment variable is deprecated as 'hf_transfer' is not used anymore. "

Two issues:

1. The string literal is constructed but never logged or warned — it's effectively dead code.
2. Even if it were logged, the condition not HF_XET_HIGH_PERFORMANCE makes it skip the most common user case (users who only know the old flag).

Suggested fix:

1. Always warn when HF_HUB_ENABLE_HF_TRANSFER is set, regardless of whether HF_XET_HIGH_PERFORMANCE is set. Use warnings.warn(...) or logger.warning(...) so the message is actually surfaced at module import or upload start.
2. Update the basic hf upload quickstart in docs/source/en/guides/upload.md to mention HF_XET_HIGH_PERFORMANCE=1 as the recommended performance flag — currently it's only mentioned in the "Upload a large folder → Tips and tricks" sub-section, which most users don't reach.
3. Mention the migration explicitly in the v1.0 release notes / migration guide for users with HF_HUB_ENABLE_HF_TRANSFER=1 set in their existing env / shell profiles.

Why this matters: Users hitting slow uploads are currently being told to set HF_HUB_DISABLE_XET=1 as a workaround (e.g., the active forum thread linked below), which falls back to single-stream LFS at ~3 Mbps. Most of them would prefer HF_XET_HIGH_PERFORMANCE=1, but nothing in their tooling tells them that flag exists. A one-line warning would close that gap.

Related:

• HF Forum: https://discuss.huggingface.co/t/upload-speeds-extremely-slow-stalling-since-april-1st/174910
• xet-core#800 — Xet stalls on GCP (separate behavioral bug)
• huggingface_hub#3726 — pre-upload progress lost on restart (related Xet bug)

Reproduction

# In a shell with the legacy flag set:
HF_HUB_ENABLE_HF_TRANSFER=1 hf upload <namespace>/<repo> ./large_file.safetensors

Expected: a deprecation warning at upload start telling the user the flag is no longer effective and pointing them to HF_XET_HIGH_PERFORMANCE.

Actual: silence. Throughput identical to running with no flag set. Confirmed via TCP destination inspection (ss -tnp shows GCS endpoints 34.107.x.x / 34.149.x.x, indicating the Xet path is in use regardless of the legacy flag).

Logs

System info

- `huggingface_hub` version: 1.14.0
- `hf-xet` version: 1.5.0
- Python version: 3.12
- OS: Linux aarch64 (NVIDIA Jetson Thor AGX)
- Token authenticated: Yes
- Run as: standard user (non-root)

[Adithya191101]

Small correction to the original report: I claimed "the string is constructed but never logged or warned" that's wrong on closer inspection. The warning is issued via warnings.warn(..., DeprecationWarning). The reason most affected users still don't see it is that Python silences DeprecationWarning by default in user-facing code (filtered out unless explicitly enabled with python -W default or PYTHONWARNINGS). So it's not dead code, but it's effectively invisible to anyone running hf upload from a normal shell.

The two real issues remain as described:

1. The condition and not HF_XET_HIGH_PERFORMANCE excludes the common user case (only the legacy flag set).
2. DeprecationWarning is silent by default for end users; switching to FutureWarning (or routing through logger.warning) would make the message actually reach the user.

I opened #4220 with both fixes — happy to iterate based on review.