环境变量

可以使用环境变量配置 huggingface_hub。

如果您不熟悉环境变量，这里有一些关于它们的通用文章：关于 macOS 和 Linux 以及关于 Windows。

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

通用

HF_INFERENCE_ENDPOINT

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

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

HF_HOME

用于配置 huggingface_hub 本地存储数据的位置。特别是，您的令牌和缓存将存储在此文件夹中。

默认为 "~/.cache/huggingface"，除非设置了 XDG_CACHE_HOME。

HF_HUB_CACHE

用于配置 Hub 中的仓库将在本地缓存的位置（模型、数据集和 Spaces）。

默认为 "$HF_HOME/hub"（例如，默认情况下为 "~/.cache/huggingface/hub"）。

HF_XET_CACHE

用于配置 Xet 区块（由 Xet 后端管理的文件中的字节范围）在本地缓存的位置。

默认为 "$HF_HOME/xet"（例如，默认情况下为 "~/.cache/huggingface/xet"）。

HF_ASSETS_CACHE

用于配置下游库创建的资产在本地缓存的位置。这些资产可以是预处理数据、从 GitHub 下载的文件、日志等。

默认为 "$HF_HOME/assets"（例如，默认情况下为 "~/.cache/huggingface/assets"）。

HF_TOKEN

用于配置用户访问令牌以向 Hub 进行身份验证。如果设置，此值将覆盖存储在机器上的令牌（在 $HF_TOKEN_PATH 或 "$HF_HOME/token" 中，如果前者未设置）。

有关身份验证的更多详细信息，请查看此部分。

HF_TOKEN_PATH

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

HF_HUB_VERBOSITY

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

默认为 "warning"。

有关更多详细信息，请参阅日志记录参考。

HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD

此环境变量已被弃用，现在被 huggingface_hub 忽略。将文件下载到本地目录不再依赖符号链接。

HF_HUB_ETAG_TIMEOUT

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

HF_HUB_DOWNLOAD_TIMEOUT

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

布尔值

以下环境变量需要布尔值。如果变量的值是 {"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 的任何方法，则会引发 OfflineModeIsEnabled 异常。

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

HF_HUB_DISABLE_IMPLICIT_TOKEN

并非每个对 Hub 的请求都需要身份验证。例如，请求关于 "gpt2" 模型的详细信息不需要身份验证。但是，如果用户已登录，则默认行为将始终发送令牌，以便于用户体验（在访问私有或门控仓库时永远不会收到 HTTP 401 Unauthorized）。为了保护隐私，您可以通过设置 HF_HUB_DISABLE_IMPLICIT_TOKEN=1 来禁用此行为。在这种情况下，令牌将仅针对“写访问”调用发送（例如：创建提交）。

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

HF_HUB_DISABLE_PROGRESS_BARS

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

HF_HUB_DISABLE_SYMLINKS_WARNING

如果您使用的是 Windows 机器，建议启用开发者模式或以管理员模式运行 huggingface_hub。否则，huggingface_hub 将无法在您的缓存系统中创建符号链接。您将能够执行任何脚本，但您的用户体验会降低，因为一些大型文件最终可能会在您的硬盘驱动器上重复。会触发警告消息以警告您有关此行为。设置 HF_HUB_DISABLE_SYMLINKS_WARNING=1 以禁用此警告。

有关更多详细信息，请参阅缓存限制。

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_ENABLE_HF_TRANSFER

设置为 True 可使用 hf_transfer 更快地从 Hub 上传和下载。

默认情况下，huggingface_hub 使用基于 Python 的 requests.get 和 requests.post 函数。虽然这些函数可靠且功能多样，但对于具有高带宽的机器来说，它们可能不是最有效的选择。hf_transfer 是一个基于 Rust 的软件包，旨在最大限度地利用带宽，它通过将大型文件分成更小的部分，并使用多线程同时传输它们来实现。这种方法有可能使传输速度提高一倍。要使用 hf_transfer，请执行以下操作：

在安装 huggingface_hub 时指定 hf_transfer 额外依赖项（例如 pip install huggingface_hub[hf_transfer]）。
设置 HF_HUB_ENABLE_HF_TRANSFER=1 作为环境变量。

请注意，使用 hf_transfer 存在一些限制。由于它不是纯粹基于 Python 的，因此调试错误可能具有挑战性。此外，hf_transfer 缺少一些用户友好的功能，例如断点续传下载和代理。这些省略是故意的，目的是保持 Rust 逻辑的简洁性和速度。因此，hf_transfer 在 huggingface_hub 中默认未启用。

hf_xet 是 hf_transfer 的替代方案。它通过基于块的去重策略、自定义 Xet 存储（取代 Git LFS）以及与 huggingface_hub 的无缝集成，提供高效的文件传输。

阅读更多关于该软件包的信息并使用 pip install huggingface_hub[hf_xet] 启用它。

已弃用的环境变量

为了标准化 Hugging Face 生态系统中的所有环境变量，一些变量已被标记为已弃用。虽然它们仍然可以工作，但它们不再优先于其替代变量。下表概述了已弃用的变量及其对应的替代变量。

已弃用变量	替代变量
`HUGGINGFACE_HUB_CACHE`	`HF_HUB_CACHE`
`HUGGINGFACE_ASSETS_CACHE`	`HF_ASSETS_CACHE`
`HUGGING_FACE_HUB_TOKEN`	`HF_TOKEN`
`HUGGINGFACE_HUB_VERBOSITY`	`HF_HUB_VERBOSITY`

来自外部工具

一些环境变量并非 huggingface_hub 特有，但在设置后仍会被考虑在内。

DO_NOT_TRACK

布尔值。等同于 HF_HUB_DISABLE_TELEMETRY。当设置为 true 时，遥测功能将在 Hugging Face Python 生态系统（transformers、diffusers、gradio 等）中全局禁用。有关更多详细信息，请参阅 https://consoledonottrack.com/。

NO_COLOR

布尔值。设置后，huggingface-cli 工具将不会打印任何 ANSI 颜色。请参阅 no-color.org。

XDG_CACHE_HOME

仅在未设置 HF_HOME 时使用！

这是在 Linux 机器上配置用户特定的非必要（缓存）数据应写入位置的默认方式。

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

< > 在 GitHub 上更新

Hub Python 库