# 环境变量

`huggingface_hub` 可以通过环境变量进行配置。

如果您对环境变量不熟悉，这里有一些关于它们的通用文章，分别介绍了 [macOS 和 Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) 以及 [Windows](https://phoenixnap.com/kb/windows-set-environment-variable) 上的相关内容。

本页面将引导您了解 `huggingface_hub` 的所有特定环境变量及其含义。

> [!TIP]
> 所有环境变量都会在导入 `huggingface_hub` 时读取。之后进行的任何修改都不会生效。请确保在导入 `huggingface_hub` 之前设置好环境变量。

## 通用

### HF_INFERENCE_ENDPOINT

用于配置推理 API 的基础 URL。如果您的组织指向 API 网关而非直接指向推理 API，您可能需要设置此变量。

默认值为 `"https://api-inference.huggingface.co"`。

### HF_HOME

用于配置 `huggingface_hub` 在本地存储数据的位置。具体来说，您的令牌和缓存将存储在此文件夹中。

如果未设置 [XDG_CACHE_HOME](#xdgcachehome)，则默认为 `"~/.cache/huggingface"`。

### HF_HUB_CACHE

用于配置从 Hub 获取的仓库（模型、数据集和空间）在本地缓存的位置。

默认值为 `"$HF_HOME/hub"`（例如，默认为 `"~/.cache/huggingface/hub"`）。

### HF_XET_CACHE

用于配置 Xet 在本地存储其分片缓存和上传暂存数据的位置。有关更多详细信息，请参阅 [Xet 缓存](../guides/manage-cache#xet-caching)。

默认值为 `"$HF_HOME/xet"`（例如，默认为 `"~/.cache/huggingface/xet"`）。

### HF_ASSETS_CACHE

用于配置下游库创建的 [assets](../guides/manage-cache#caching-assets) 在本地缓存的位置。这些资源可以是预处理后的数据、从 GitHub 下载的文件、日志等。

默认值为 `"$HF_HOME/assets"`（例如，默认为 `"~/.cache/huggingface/assets"`）。

### HF_TOKEN

用于配置 User Access Token 以向 Hub 进行身份验证。如果设置了此值，它将覆盖机器上存储的 token（位于 `$HF_TOKEN_PATH`，或者如果前者未设置，则位于 `"$HF_HOME/token"`）。

有关身份验证的更多详细信息，请参阅[此部分](../quick-start#authentication)。

### HF_TOKEN_PATH

用于配置 `huggingface_hub` 存储用户访问令牌的位置。默认值为 `"$HF_HOME/token"`（例如，默认为 `~/.cache/huggingface/token`）。

### HF_HUB_VERBOSITY

设置 `huggingface_hub` 日志记录器的详细程度级别。必须是 `{"debug", "info", "warning", "error", "critical"}` 之一。

默认值为 `"warning"`。

有关更多详细信息，请参阅[日志记录参考](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity)。

### HF_HUB_ETAG_TIMEOUT

用于定义在从仓库获取最新元数据之前等待服务器响应的秒数的整数值。如果请求超时，`huggingface_hub` 将默认使用本地缓存的文件。对于已缓存文件但网络连接较慢的机器，设置较低的值可以加快工作流速度。较高的值则能保证元数据调用在更多情况下成功。默认值为 10 秒。

### HF_HUB_DOWNLOAD_TIMEOUT

用于定义下载文件时等待服务器响应的秒数的整数值。如果请求超时，将引发 TimeoutError。在连接较慢的机器上，设置较高的值会有所帮助。在完全断网的情况下，较小的值会使进程更快地失败。默认值为 10 秒。

## Xet 

### 其他 Xet 环境变量
* [`HF_HUB_DISABLE_XET`](../package_reference/environment_variables#hfhubdisablexet)
* [`HF_XET_CACHE`](../package_reference/environment_variables#hfxetcache)
* [`HF_XET_HIGH_PERFORMANCE`](../package_reference/environment_variables#hfxethighperformance)
* [`HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY`](../package_reference/environment_variables#hfxetreconstructwritesequentially)

### HF_XET_CHUNK_CACHE_SIZE_BYTES

此变量不再有任何效果。`hf_xet` 不再使用本地块缓存进行下载，设置此变量也不会启用该功能。详情请参见 [xet-core#715](https://github.com/huggingface/xet-core/issues/715)。

### HF_XET_SHARD_CACHE_SIZE_LIMIT

用于在本地设置 Xet 分片缓存的大小。增大此值可提高上传效率，因为缓存分片文件中引用的数据块不会被重复上传。请注意，默认的软限制对于大多数工作负载而言可能已经足够。

默认值为 `16000000000`（16GB）。

### HF_XET_NUM_CONCURRENT_RANGE_GETS

此变量已不再使用。自 `hf_xet` 1.3.0 起，下载并发度由系统自适应控制。

## 布尔值

以下环境变量期望一个布尔值。如果其值为 `{"1", "ON", "YES", "TRUE"}` 之一（不区分大小写），则该变量被视为 `True`。任何其他值（或未定义）都将被视为 `False`。

### HF_DEBUG

如果已设置，`huggingface_hub` 记录器的日志级别将被设置为 DEBUG。此外，HF 库发出的所有请求都会以等效的 cURL 命令形式记录，以便于调试和复现。

### HF_HUB_OFFLINE

如果已设置，则不会向 Hugging Face Hub 发起任何 HTTP 调用。如果您尝试下载文件，则只会访问已缓存的文件。如果未检测到缓存文件，则会引发错误。这在您的网络较慢且您不关心文件是否为最新版本时非常有用。

如果将 `HF_HUB_OFFLINE=1` 设置为环境变量，并且你调用了 [HfApi](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi) 的任何方法，则会抛出 [OfflineModeIsEnabled](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.OfflineModeIsEnabled) 异常。

**注意：**即使文件的最新版本已缓存，调用 `hf_hub_download` 仍会触发 HTTP 请求以检查是否有新版本可用。设置 `HF_HUB_OFFLINE=1` 可跳过此调用，从而加快加载速度。

如果您想检查是否启用了离线模式，可以使用 [is_offline_mode()](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.is_offline_mode) 辅助函数。

### HF_HUB_DISABLE_IMPLICIT_TOKEN

并非所有对 Hub 的请求都需要身份验证。例如，请求 `"gpt2"` 模型的详细信息时无需进行身份验证。但是，如果用户已[登录](../package_reference/login)，默认行为是始终发送令牌，以便在访问私有或受限仓库时提升用户体验（避免收到 HTTP 401 Unauthorized 错误）。出于隐私考虑，您可以通过设置 `HF_HUB_DISABLE_IMPLICIT_TOKEN=1` 来禁用此行为。在这种情况下，令牌仅会在“写入访问”调用（例如：创建提交）时发送。

**注意：**禁用隐式发送 token 可能会产生奇怪的副作用。例如，如果你想列出 Hub 上的所有模型，你的私有模型将不会被列出。你需要在脚本中显式传入 `token=True` 参数。

### HF_HUB_DISABLE_PROGRESS_BARS

对于耗时较长的任务，`huggingface_hub` 默认会显示进度条（使用 tqdm）。你可以通过设置 `HF_HUB_DISABLE_PROGRESS_BARS=1` 一次性禁用所有进度条。

### HF_HUB_DISABLE_SYMLINKS

如果设置了该选项，`huggingface_hub` 将不会在缓存中创建符号链接。相反，文件会被直接复制或移动到快照目录中。这是一个面向高级用户的特性，会使缓存目录以降级模式运行，导致大文件在硬盘上被重复存储。

一个典型的使用场景是，当跨不同操作系统运行的机器使用共享网络驱动器（例如 NAS）作为 `HF_HUB_CACHE` 时。在 Linux 上创建的符号链接在 Windows 上并不总是可访问的，从而导致错误。设置 `HF_HUB_DISABLE_SYMLINKS=1` 可以避免此问题，但代价是失去磁盘空间的去重功能。

### HF_HUB_DISABLE_SYMLINKS_WARNING

如果您使用的是 Windows 系统，建议启用开发者模式，或以管理员模式运行 `huggingface_hub`。否则，`huggingface_hub` 将无法在您的缓存系统中创建符号链接。您仍然可以运行任何脚本，但由于一些大文件可能会在硬盘上被重复存储，您的用户体验将会下降。系统会触发一条警告消息来提醒您这一行为。设置 `HF_HUB_DISABLE_SYMLINKS_WARNING=1` 可禁用此警告。

有关更多详细信息，请参阅[缓存限制](../guides/manage-cache#limitations)。

### HF_HUB_DISABLE_EXPERIMENTAL_WARNING

`huggingface_hub` 的部分功能属于实验性功能。这意味着你可以使用它们，但我们不保证未来会持续维护。特别是，我们可能会在没有弃用周期的情况下更新此类功能的 API 或行为。使用实验性功能时会触发警告消息以提醒你注意。如果你能够自行调试使用实验性功能时可能出现的任何问题，可以设置 `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` 来禁用该警告。

如果您正在使用实验性功能，请告诉我们！您的反馈有助于我们对其进行设计和改进。

### HF_HUB_DISABLE_TELEMETRY

默认情况下，部分数据会由 HF 库（`transformers`、`datasets`、`gradio` 等）收集，用于监控使用情况、调试问题以及帮助确定功能优先级。每个库都会定义自己的策略（即监控哪些使用情况），但核心实现在 `huggingface_hub` 中完成（参见 `send_telemetry`）。

您可以将 `HF_HUB_DISABLE_TELEMETRY=1` 设置为环境变量，以全局禁用遥测功能。

### HF_HUB_DISABLE_UPDATE_CHECK

默认情况下，`hf` CLI 在启动时会检查 PyPI 上是否有更新的版本（最多每 24 小时检查一次），如果有可用版本，则向 stderr 打印一行黄色警告，并建议运行 `hf update`。对于开发版和预发布版，该检查本身即为空操作。

它还会（最多每 24 小时一次，完全在本地）检查 `hf-cli` 技能是否已安装且由当前运行版本生成，若未满足则建议执行 `hf skills add` / `hf skills update`。该检查仅打印提示信息，绝不会修改您的技能目录。

在运行已安装的 [CLI 扩展](../guides/cli-extensions) 之前，它会检查（每个扩展最多每 24 小时一次）GitHub 上是否有更新的提交，如果有，则建议运行 `hf extensions update <name>`。`hf extensions list` 的 `LATEST` 列也使用相同的检查机制。

设置 `HF_HUB_DISABLE_UPDATE_CHECK=1` 可跳过这些请求并屏蔽所有相关提示。这在离线 CI 环境中，或当你希望终端输出更简洁时非常有用。

### HF_HUB_DISABLE_XET

设置为禁用 `hf-xet`，即使它在您的 Python 环境中可用。这是因为如果检测到 `hf-xet`，它将被自动使用，此设置允许显式禁用其使用。如果您禁用了 Xet，请考虑[提交问题并包含诊断](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging)信息，以帮助我们了解为什么 Xet 对您不起作用。

### HF_HUB_ENABLE_HF_TRANSFER

> [!WARNING]
> 这是一个已弃用的环境变量。现在 Hugging Face Hub 已完全由 Xet 存储后端提供支持，所有文件传输均通过 `hf-xet` 二进制包进行。它采用基于块的重复数据删除策略，提供高效的传输，并与 `huggingface_hub` 无缝集成。这意味着 `hf_transfer` 已无法再使用。如果您对更高的性能感兴趣，请查看 [`HF_XET_HIGH_PERFORMANCE` 部分](#hf_xet_high_performance)

### HF_HUB_DISABLE_SHARED_BLOBS

将其设置为 `1` 可禁用缓存范围的共享 blob 存储。默认情况下，成功下载的 Xet 文件会存储在 `<CACHE_DIR>/blobs/<prefix>/<xet_hash>` 中，并通过符号链接引入到仓库缓存中，因此相同的文件在磁盘上跨仓库仅存储一次，且无需重新获取即可复用。此优化功能默认启用，但如果 Xet 不可用（例如设置了 `HF_HUB_DISABLE_XET=1`）或本地不支持符号链接，则会被禁用。在这些情况下，系统会静默回退到常规的仓库本地存储。有关详细信息，请参阅 [缓存指南](../guides/manage-cache#shared-blobs-across-repos)。

### HF_XET_HIGH_PERFORMANCE

将 `hf-xet` 设置为以更高的配置运行，以最大化利用机器上的网络和磁盘资源。启用高性能模式将尝试占满该机的网络带宽，并利用所有 CPU 核心进行并行上传/下载操作。

可以将其类比为旧的环境变量 `HF_HUB_ENABLE_HF_TRANSFER=1`，只不过它应用于 `hf-xet`。

要了解 Xet 存储和 `hf_xet` 的优势，请参阅此 [章节](https://huggingface.co/docs/hub/xet/index)。

### HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

此变量已不再使用。自 `hf_xet` 1.3.0 起，文件始终按顺序写入本地磁盘（参见 [v1.3.0 中的文件写入器](https://github.com/huggingface/xet-core/blob/v1.3.0/file_reconstruction/src/data_writer/data_writer.rs#L76-L91)）。

## 已弃用的环境变量

为了统一 Hugging Face 生态系统中的所有环境变量，部分变量已被标记为弃用。尽管它们仍然可用，但不再优先于其替代变量。下表列出了已弃用的变量及其对应的替代变量：

| 已弃用的变量         | 替换        |
| --------------------------- | ------------------ |
| `HUGGINGFACE_HUB_CACHE`     | `HF_HUB_CACHE`     |
| `HUGGINGFACE_ASSETS_CACHE`  | `HF_ASSETS_CACHE`  |
| `HUGGING_FACE_HUB_TOKEN`    | `HF_TOKEN`         |

## 来自外部工具

某些环境变量并非`huggingface_hub` 所特有，但在设置时仍会被考虑在内。

### DO_NOT_TRACK

布尔值。等效于 `HF_HUB_DISABLE_TELEMETRY`。当设置为 true 时，将在 Hugging Face Python 生态系统（`transformers`、`diffusers`、`gradio` 等）中全局禁用遥测。有关更多详细信息，请访问 https://donottrack.sh/。

### NO_COLOR

布尔值。设置后，`hf` CLI 将不会输出任何 ANSI 颜色。参见 [no-color.org](https://no-color.org/)。

### XDG_CACHE_HOME

仅在未设置 `HF_HOME` 时使用！

在 Linux 机器上，这是配置[用户特定的非关键（缓存）数据应写入位置](https://wiki.archlinux.org/title/XDG_Base_Directory)的默认方式。

如果未设置 `HF_HOME`，默认主目录将是 `"$XDG_CACHE_HOME/huggingface"`，而不是 `"~/.cache/huggingface"`。