Extra requirement hf_transfer is broken for some pip versions

[Stannislav]

Describe the bug

There are versions of pip which the extra requirement hf_transfer doesn't work - the hf_transfer package is not installed.

Reproduction

Use pip version 22.0.2 and verify that the package hf-transfer is not installed:

$ pip install pip==22.0.2
$ pip install 'huggingface-hub[hf_transfer]'
$ pip freeze | grep hf_transfer
# nothing

Newer pip versions install hf-transfer:

$ pip install --upgrade pip
$ pip install 'huggingface-hub[hf_transfer]'
$ pip freeze | grep hf_transfer
hf_transfer==0.1.9

Details

The release workflow uses setuptools version 58.1.0, which was released in 2021.

This version produces a wheel file in which the definition of the hf_transfer extra in the METADATA file is inconsistent:

$ pip install setuptools==58.1.0
$ rm -rf build dist
$ python setup.py bdist_wheel
$ unzip -c dist/huggingface_hub-0.31.0.dev0-py3-none-any.whl huggingface_hub-0.31.0.dev0.dist-info/METADATA | grep transfer
...
Provides-Extra: hf_transfer
Requires-Dist: hf-transfer>=0.1.4; extra == "hf-transfer"

Note the difference between the two lines: one uses an underscore (hf_transfer), the other a hyphen (hf-transfer).

It appears that older pip versions can't handle this correctly:

$ pip install pip==22.0.2
$ pip install 'dist/huggingface_hub-0.31.0.dev0-py3-none-any.whl[hf_transfer]'
Installing collected packages: urllib3, typing-extensions, tqdm, pyyaml, packaging, idna, hf-xet, fsspec, filelock, charset-normalizer, certifi, requests, huggingface-hub
Successfully installed certifi-2025.1.31 charset-normalizer-3.4.1 filelock-3.18.0 fsspec-2025.3.2 hf-xet-1.0.3 huggingface-hub-0.31.0.dev0 idna-3.10 packaging-25.0 pyyaml-6.0.2 requests-2.32.3 tqdm-4.67.1 typing-extensions-4.13.2 urllib3-2.4.0
# Note: hf-transfer was NOT installed.

# Try the same install command again, but with upgraded pip.
$ pip install --upgrade pip
Successfully installed pip-25.0.1
$ pip install 'dist/huggingface_hub-0.31.0.dev0-py3-none-any.whl[hf_transfer]'
Installing collected packages: hf-transfer
Successfully installed hf-transfer-0.1.9
# Now hf-transfer WAS installed.

The difference in the extra name in METADATA does not happen with newer releases of setuptools:

$ pip install --upgrade setuptools
Successfully installed setuptools-79.0.1
$ rm -rf build dist
$ python setup.py bdist_wheel
$ unzip -c dist/huggingface_hub-0.31.0.dev0-py3-none-any.whl huggingface_hub-0.31.0.dev0.dist-info/METADATA | grep transfer
Provides-Extra: hf-transfer
Requires-Dist: hf_transfer>=0.1.4; extra == "hf-transfer"

Now the extra name in the two lines is identical.

I was going to create a pull request which upgrades setuptools in the release workflow, but I'm noting that in the name of the extra the underscore was replaced by a hyphen: hf-transfer instead of hf_transfer. Since the documentation uses hf_transfer this would be a breaking change. So, I'm leaving this here as an issue to discuss the path forward

Logs

System info

- Platform: macOS-15.4-arm64-arm-64bit
- Python version: 3.9.6

[hanouticelina]

Thank you @Stannislav for reporting this!
If i understand correctly, the bug is a combination of setuptools <= 58 (writes inconsistent metadata) and pip <= 22 (doesn’t normalize extra names).
in my opinion, upgrading setuptools in the release workflow is the best solution in this case. This fixes the hf_transfer / hf-transfer metadata inconsistency. However, i'm not sure how it's a breaking change, users should still be able to use pip install huggingface-hub[hf_transfer] (with the underscore) even after upgrading setuptools, right? Correct me if i'm wrong, but the only "breaking" change i see is if someone is using pip <= 22 and insists on writing the underscore form, but that combination already fails today, so we’re not introducing a new regression.