Transformers 安装指南：从 pip 到离线部署，一文掌握 transformers 5.x 的完整安装与缓存配置

本篇基于当前 transformers 仓库（版本 5.16.0.dev0，setup.py 中声明）的官方阿拉伯语安装文档整理成文，覆盖 pip / 源码 / 可编辑 / conda 四种安装路径、模型缓存目录机制与离线（无网络）部署方案。读完后，你可以在任意环境中正确安装 Transformers、配置 HF_HUB_CACHE 缓存，并通过 HF_HUB_OFFLINE 与 local_files_only 参数在内网环境中稳定加载预训练模型。

运行环境与依赖前提

Transformers 当前已测试支持 Python 3.10 及更高版本、PyTorch 2.4 及更高版本。从 setup.py 的源码结构可以看到，仓库明确定义 SUPPORTED_PYTHON_VERSIONS = (10, 14)（即 Python 3.10–3.14），并据此动态生成 python_requires 元数据。

硬性依赖（install_requires）在 setup.py 中列出，安装任何方式都会自动带上：

• huggingface-hub>=1.5.0,<2.0：模型 Hub 下载与缓存的核心；
• numpy>=1.17、packaging、pyyaml、regex；
• tokenizers>=0.23.1,<0.24.0：快速分词器（Rust 后端）；
• typer：提供 transformers 命令行工具（入口见 setup.py 中的 entry_points）；
• safetensors>=0.8.0、tqdm>=4.60。

深度学习框架则通过 extras 按需安装，例如 setup.py 中 extras["torch"] = deps_list("torch", "accelerate")，对应 PyTorch 2.5+ 与 accelerate>=1.1.0；另有 vision（torchvision + Pillow）、audio（torchaudio、librosa 等）、serving（FastAPI/Starlette/OpenAI 兼容服务端）等组合，可按任务按需叠加。

使用 pip 安装

官方要求将 Transformers 安装在 Python 虚拟环境 中（此处保留原文档指向 Python 官方文档 venv 与打包指南的外部链接，便于查阅）。虚拟环境便于隔离不同项目、避免依赖冲突。在项目目录下创建并激活虚拟环境：

python -m venv .env

在 Linux 与 macOS 上激活：

source .env/bin/activate

在 Windows 上激活：

.env/Scripts/activate

然后安装：

pip install transformers

若只需要 CPU 支持，可以用 extras 一步装好 Transformers 与深度学习框架，例如：

pip install 'transformers[torch]'

注意：如果需要 GPU（CUDA），请先按 PyTorch 官方指南安装与驱动匹配的 CUDA 版 PyTorch，再安装 Transformers；transformers[torch] 拉取的是默认 PyPI 上的 torch。

验证安装是否成功

安装完成后，运行以下命令验证（会自动从 Hub 下载一个预训练模型）：

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('we love you'))"

输出标签与置信度，形如：

[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

如果能看到 POSITIVE 标签，说明安装、依赖与网络下载链路均已正常工作。

从源码安装（main 分支）

通过以下命令直接从源码安装：

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

该命令安装的是 main 分支的最新开发版，而非稳定发布版。main 版适合紧跟最新进展——例如某个 bug 已在 main 修复但尚未发版。代价是 main 分支不保证永远稳定：仓库会尽力保持 main 可运行，大多数问题通常数小时到一天内解决；如遇问题，建议在仓库 issue 区提交缺陷报告以便尽快修复。

验证方式与 pip 安装相同：

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('I love you'))"

可编辑安装（editable install）

如果你满足以下任一条件，应使用可编辑安装：

• 想直接使用 main 分支源码；
• 要参与 Transformers 开发，需要对代码改动做即时测试。

克隆仓库并以可编辑模式安装：

git clone https://github.com/huggingface/transformers.git
cd transformers
pip install -e .

这些命令会把克隆目录与 Python 的包搜索路径链接起来：Python 除常规 site-packages 外，还会到克隆目录中查找 transformers 包。例如，如果包通常安装在 ~/anaconda3/envs/main/lib/python3.10/site-packages/，Python 现在也会查找 ~/transformers/。

重要提示：如果你要继续使用该库，必须保留 transformers 克隆目录，删除后库将不可用。

之后可随时同步到最新 main：

cd ~/transformers/
git pull

下一次运行 Python 时即生效。对于参与贡献的开发者，仓库还内置了代码质量检查流程（见 Makefile 中的 make fix-repo / make quality），修改 setup.py 依赖表后需运行 make fix-repo 重新生成 dependency_versions_table.py。

使用 conda 安装

可从 conda-forge 渠道安装：

conda install conda-forge::transformers

配置模型缓存目录

预训练模型下载后默认缓存在 ~/.cache/huggingface/hub，该路径由环境变量 HF_HUB_CACHE 指定。在 Windows 上，默认缓存目录为 C:\Users\username\.cache\huggingface\hub。

缓存目录的解析按以下优先级进行（可依次覆盖）：

1. 环境变量（默认）：HF_HUB_CACHE；
2. 环境变量：HF_HOME（HF_HUB_CACHE 未设置时，在其下派生 hub 缓存路径）；
3. 环境变量：XDG_CACHE_HOME + /huggingface（Linux 下的 XDG 规范）。

从源码看，仓库内动态模块缓存 HF_MODULES_CACHE 同样以 HF_HOME 为基准派生，参见 src/transformers/utils/hub.py 中 os.getenv("HF_MODULES_CACHE", os.path.join(constants.HF_HOME, "modules")) 的实现，可见 HF_HOME 是整个 Hugging Face 缓存体系的根变量，统一改 HF_HOME 即可迁移全部缓存位置。

离线（offline）运行

在内网、防火墙保护或完全无网环境中，可通过设置环境变量 HF_HUB_OFFLINE=1，让 Transformers 只使用本地已缓存的文件：

HF_DATASETS_OFFLINE=1 HF_HUB_OFFLINE=1 \
python examples/pytorch/translation/run_translation.py --model_name_or_path google-t5/t5-small --dataset_name wmt16 --dataset_config ro-en ...

对应的训练脚本 examples/pytorch/translation/run_translation.py 确实存在于仓库中。设置后该脚本应能无卡顿、无超时地运行，因为模型加载不会再尝试从 Hub 下载。

另外，也可以在每次 [~PreTrainedModel.from_pretrained] 调用时用参数 local_files_only=True 跳过 Hub，只加载本地文件：

from transformers import T5Model

model = T5Model.from_pretrained("./path/to/local/directory", local_files_only=True)

该参数在 src/transformers/modeling_utils.py 的 from_pretrained 实现中作为核心开关被处理（源码中多处引用），语义是“绝不发起网络请求”。

预下载模型与分词器以备离线使用

离线使用的另一种思路是：先联网下载文件，之后直接指向本地路径。有三种方式：

1. 通过 Model Hub 网页手动下载：在 Model Hub 页面上点击模型文件旁的下载图标（↓）逐一下载。

2. 使用 from_pretrained + save_pretrained 工作流（推荐，一次缓存全套文件）：

   1. 联网时预下载：

   >>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
   
   >>> tokenizer = AutoTokenizer.from_pretrained("bigscience/T0_3B")
   >>> model = AutoModelForSeq2SeqLM.from_pretrained("bigscience/T0_3B")
   

   2. 保存到指定本地目录：

   >>> tokenizer.save_pretrained("./your/path/bigscience_t0")
   >>> model.save_pretrained("./your/path/bigscience_t0")
   

   3. 离线时从该目录重新加载：

   >>> tokenizer = AutoTokenizer.from_pretrained("./your/path/bigscience_t0")
   >>> model = AutoModel.from_pretrained("./your/path/bigscience_t0")
   

3. 用 huggingface_hub 编程式下载单个文件：

   1. 在虚拟环境中安装：

   python -m pip install huggingface_hub
   

   2. 用 hf_hub_download 把文件下载到指定路径，例如下载 T0 模型的 config.json：

   >>> from huggingface_hub import hf_hub_download
   
   >>> hf_hub_download(repo_id="bigscience/T0_3B", filename="config.json", cache_dir="./your/path/bigscience_t0")
   

文件下载并本地缓存后，直接指向其本地路径即可加载：

>>> from transformers import AutoConfig

>>> config = AutoConfig.from_pretrained("./your/path/bigscience_t0/config.json")

补充：transformers download 命令行

除上述 Python API 外，当前版本还内置了 transformers download 子命令（由 src/transformers/cli/download.py 实现，入口注册见 setup.py），支持 --cache-dir 指定下载目录，并可配合 --trust-remote-code 下载含自定义代码的模型。仓库测试 tests/cli/test_download.py 验证了该命令下载后会在缓存目录生成标准的 blobs / refs / snapshots 三段式结构——这正是 ~/.cache/huggingface/hub 下每个仓库缓存的目录布局，也解释了为什么“指向缓存目录”即可实现离线加载。

小结

• 日常使用：python -m venv .env 建虚拟环境，pip install 'transformers[torch]' 一步到位；
• 追求最新修复：pip install git+https://github.com/huggingface/transformers，或用 git clone + pip install -e . 的可编辑安装配合 git pull 持续更新；
• conda 用户：conda install conda-forge::transformers；
• 缓存管理：优先改 HF_HUB_CACHE，其次 HF_HOME，最后回落到 XDG_CACHE_HOME/huggingface；
• 离线部署：HF_HUB_OFFLINE=1（配 HF_DATASETS_OFFLINE=1）+ 预下载文件，或加载时传 local_files_only=True。