环境变量

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 下载的代码仓库（模型、数据集和空间）在本地的缓存位置。

默认为 "$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 秒。

Xet

其他 Xet 环境变量

HF_XET_CHUNK_CACHE_SIZE_BYTES

用于在本地设置 Xet 数据块缓存的大小。增加此值将为从 S3 获取的术语/数据块提供更多缓存空间。更大的缓存可以更好地利用跨代码仓库和文件的重复数据删除。如果你的网络速度远大于本地磁盘速度（例如 10Gbps 与 SSD 或更差），则可以考虑禁用 Xet 缓存以提高性能。要禁用 Xet 缓存，请设置 HF_XET_CHUNK_CACHE_SIZE_BYTES=0。

默认为 10000000000（10GB）。

HF_XET_SHARD_CACHE_SIZE_LIMIT

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

默认为 4000000000（4GB）。

HF_XET_NUM_CONCURRENT_RANGE_GETS

用于设置每个文件从 S3 下载的并发术语（xorb 内的字节范围，通常称为数据块）的数量。如果网络带宽可用，增加此值将有助于提高文件下载速度。

默认为 16。

布尔值

以下环境变量需要布尔值。如果变量的值是 {"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 未授权错误）。出于隐私考虑，你可以通过设置 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_DISABLE_XET

设置为禁用 hf-xet，即使它在你的 Python 环境中可用。由于 hf-xet 如果被找到就会自动使用，这个设置允许明确禁用其使用。

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]" 启用。

HF_XET_HIGH_PERFORMANCE

将 hf-xet 设置为以增强的设置运行，以最大化机器上的网络和磁盘资源。启用高性能模式将尝试饱和此机器的网络带宽，并利用所有 CPU 内核进行并行上传/下载活动。可以认为这与使用 hf-xet 上传/下载到 Xet 存储后端时设置 HF_HUB_ENABLE_HF_TRANSFER=True 类似。

HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

让 hf-xet 按顺序写入本地磁盘，而不是并行写入。hf-xet 是为 SSD/NVMe 磁盘设计的（使用直接寻址的并行写入）。如果你使用的是 HDD（机械硬盘），设置此项将把磁盘写入方式改为顺序写入而不是并行写入。对于较慢的硬盘，这可以提高整体写入性能，因为磁盘不需要为了并行写入而旋转寻道。

已弃用的环境变量

为了标准化 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

布尔值。设置后，hf 命令行界面将不会打印任何 ANSI 颜色。参见 no-color.org。

XDG_CACHE_HOME

仅在未设置 HF_HOME 时使用！

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

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

< > 在 GitHub 上更新

Hub Python 库