# 安装

在开始之前，您需要通过安装相应的软件包来配置环境。

`huggingface_hub` 在 **Python 3.10+** 上进行了测试。

## 使用 pip 安装

强烈建议在[虚拟环境](https://docs.python.org/3/library/venv.html)中安装`huggingface_hub`。如果您不熟悉 Python 虚拟环境，请查看此[指南](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)。虚拟环境有助于管理不同的项目，并避免依赖项之间的兼容性问题。

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

```bash
python -m venv .venv
```

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

```bash
source .venv/bin/activate
```

在 Windows 上激活虚拟环境：

```bash
.venv/Scripts/activate
```

现在，您可以准备从 [PyPi 注册表](https://pypi.org/project/huggingface-hub/)安装 `huggingface_hub`：

```bash
pip install --upgrade huggingface_hub
```

完成后，[检查安装](#check-installation)是否正常工作。

### 安装可选依赖项

`huggingface_hub` 的部分依赖项是[可选的](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies)，因为运行 `huggingface_hub` 的核心功能并不需要它们。但是，如果未安装这些可选依赖项，`huggingface_hub` 的某些功能可能无法使用。

您可以通过 `pip` 安装可选依赖项：
```bash
# Install dependencies for both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'
```

以下是 `huggingface_hub` 中可选依赖项的列表：
- `fastai`、`torch`：用于运行框架特定功能的依赖项。
- `dev`：用于向该库贡献代码的依赖项。包括 `testing`（用于运行测试）、`typing`（用于运行类型检查器）和 `quality`（用于运行代码检查工具）。

### 从源代码安装

在某些情况下，直接从源代码安装 `huggingface_hub` 会很有用。这样你可以使用最新的 `main` 版本，而不是最新的稳定版本。`main` 版本有助于你紧跟最新进展，例如，如果某个 bug 在上次正式发布后已被修复，但新版本尚未发布，此时使用 `main` 版本就非常有用。

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

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

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

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

完成后，[检查安装](#check-installation)是否正常工作。

### 可编辑安装

从源代码安装可以设置[可编辑安装](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)。如果您计划为`huggingface_hub`做出贡献并需要测试代码中的更改，这是一种更高级的安装方式。您需要在本地机器上克隆`huggingface_hub`的副本。

```bash
# 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/` 文件夹。

## 安装 Hugging Face CLI 

使用我们的一行安装命令来设置 `hf` CLI，而无需改动您的 Python 环境：

在 macOS 和 Linux 上：

```bash
curl -LsSf https://hf.co/cli/install.sh | bash
```

在 Windows 上：

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
```

要升级现有安装，请运行 `hf update` — 它会检测 `hf` 的安装方式（独立安装程序、Homebrew 或 pip），并执行相应的命令。

## 使用 conda 安装

如果您更熟悉该工具，可以使用 [conda-forge 频道](https://anaconda.org/conda-forge/huggingface_hub) 安装 `huggingface_hub`：

```bash
conda install -c conda-forge huggingface_hub
```

完成后，[检查安装](#check-installation)是否正常工作。

## 检查安装

安装完成后，运行以下命令以检查 `huggingface_hub` 是否正常工作：

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

此命令将从 Hub 获取有关 [gpt2](https://huggingface.co/gpt2) 模型的信息。输出应如下所示：

```text
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 的系统上都能正确运行。不过，`huggingface_hub` 在 Windows 上运行时存在一些限制。以下是已知问题的详尽列表。如果您遇到任何未记录的问题，请通过 [在 Github 上提交 issue](https://github.com/huggingface/huggingface_hub/issues/new/choose) 告知我们。

- `huggingface_hub` 的缓存系统依赖符号链接来高效缓存已下载的文件
from the Hub。在 Windows 上，你必须启用开发者模式或以管理员身份运行脚本，才能启用符号链接。如果未启用，缓存系统仍然可以工作，但并非以优化方式运行。有关更多详细信息，请参阅[缓存限制](./guides/manage-cache#limitations)部分。
- Hub 上的文件路径可以包含特殊字符（例如 `"path/to?/my/file"`）。Windows
对[特殊字符](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names)的限制更为严格，导致在 Windows 上无法下载这些文件。希望这种情况很少见。如果您认为这是一个错误，请联系仓库所有者；或者联系我们，以便我们找到解决方案。

## 后续步骤

当 `huggingface_hub` 已在您的机器上正确安装后，您可能需要[配置环境变量](package_reference/environment_variables)或[查看我们的指南之一](guides/overview)以开始使用。