安装

在开始之前，您需要通过安装适当的软件包来设置您的环境。

huggingface_hub 在 Python 3.8+ 上进行了测试。

使用 pip 安装

强烈建议在虚拟环境中安装 huggingface_hub。如果您不熟悉 Python 虚拟环境，请查看此指南。虚拟环境使管理不同的项目变得更容易，并避免依赖项之间的兼容性问题。

首先在您的项目目录中创建一个虚拟环境

python -m venv .env

激活虚拟环境。在 Linux 和 macOS 上

source .env/bin/activate

在 Windows 上激活虚拟环境

.env/Scripts/activate

现在您已准备好从 PyPi 注册表安装 huggingface_hub

pip install --upgrade huggingface_hub

完成后，检查安装是否正常工作。

安装可选依赖项

huggingface_hub 的某些依赖项是可选的，因为它们不是运行 huggingface_hub 核心功能所必需的。但是，如果未安装可选依赖项，huggingface_hub 的某些功能可能不可用。

您可以通过 pip 安装可选依赖项

# Install dependencies for tensorflow-specific features
# /!\ Warning: this is not equivalent to `pip install tensorflow`
pip install 'huggingface_hub[tensorflow]'

# Install dependencies for both torch-specific and CLI-specific features.
pip install 'huggingface_hub[cli,torch]'

以下是 huggingface_hub 中的可选依赖项列表

• cli: 为 huggingface_hub 提供更方便的 CLI 界面。
• fastai, torch, tensorflow: 运行框架特定功能的依赖项。
• dev: 贡献于库的依赖项。包括 testing（运行测试）、typing（运行类型检查器）和 quality（运行 linter）。

从源代码安装

在某些情况下，直接从源代码安装 huggingface_hub 会很有趣。这允许您使用最前沿的 main 版本而不是最新的稳定版本。main 版本对于保持最新发展很有用，例如，如果自上次官方发布以来已修复了一个错误但尚未发布新版本。

但是，这意味着 main 版本可能并不总是稳定的。我们努力使 main 版本保持运行，并且大多数问题通常在几个小时或一天内解决。如果您遇到问题，请打开一个 Issue，以便我们更快地修复它！

pip install git+https://github.com/huggingface/huggingface_hub

从源代码安装时，您还可以指定一个特定的分支。如果您想测试尚未合并的新功能或新错误修复，这会很有用

pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch

完成后，检查安装是否正常工作。

可编辑安装

从源代码安装允许您设置可编辑安装。如果您计划为 huggingface_hub 贡献并需要测试代码更改，这是一种更高级的安装方式。您需要在您的机器上克隆 huggingface_hub 的本地副本。

# First, clone repo locally
git clone https://github.com/huggingface/huggingface_hub.git

# Then, install with -e flag
cd huggingface_hub
pip install -e .

这些命令将您克隆仓库的文件夹链接到您的 Python 库路径。Python 现在除了正常的库路径外，还会在您克隆的文件夹中查找。例如，如果您的 Python 包通常安装在 ./.venv/lib/python3.13/site-packages/ 中，Python 也会搜索您克隆的文件夹 ./huggingface_hub/。

使用 conda 安装

如果您更熟悉它，您可以使用 conda-forge 频道安装 huggingface_hub

conda install -c conda-forge huggingface_hub

完成后，检查安装是否正常工作。

检查安装

安装后，通过运行以下命令检查 huggingface_hub 是否正常工作

python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"

此命令将从 Hub 获取有关 gpt2 模型的信息。输出应如下所示

Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation

Windows 限制

为了实现机器学习普惠化的目标，我们构建了 huggingface_hub，使其成为一个跨平台库，尤其是在基于 Unix 和 Windows 系统上都能正常工作。但是，在 Windows 上运行 huggingface_hub 时，在少数情况下存在一些限制。以下是已知问题的详尽列表。如果您遇到任何未记录的问题，请通过在 Github 上提交 Issue 告知我们。

• huggingface_hub 的缓存系统依赖于符号链接来高效地缓存从 Hub 下载的文件。在 Windows 上，您必须激活开发人员模式或以管理员身份运行脚本才能启用符号链接。如果未激活，缓存系统仍然可以工作，但效率不高。有关更多详细信息，请阅读缓存限制部分。
• Hub 上的文件路径可能包含特殊字符（例如 "path/to?/my/file"）。Windows 对特殊字符的限制更严格，这导致在 Windows 上无法下载这些文件。希望这种情况很少见。如果您认为这是一个错误，请联系仓库所有者，或者联系我们以找出解决方案。

后续步骤

在您的机器上正确安装 huggingface_hub 后，您可能需要配置环境变量或查看我们的指南之一以开始使用。