💾 如何更改 Hugging Face 模型下载缓存位置？只需设置一个环境变量（Windows）

作者：AITechLab
日期：2025年07月24日
标签：#HuggingFace #AI开发 #大模型 #缓存路径 #Windows #Python

---

🚨 为什么我要改 Hugging Face 的缓存位置？

当你使用 transformers 或 diffusers 等库从 Hugging Face 下载模型时，系统会默认将模型保存在：

C:\Users\你的用户名\.cache\huggingface\

随着模型越来越大（如 Llama、Qwen 动辄 100GB+），很容易把 C 盘撑爆！

 

✅ 解决方案：通过设置环境变量，把缓存路径改到 D 盘或其他大容量磁盘。

---

✅ 最简单的方法：设置环境变量 HF_HOME

Hugging Face 官方提供了一个全局变量 HF_HOME 和 HUGGINGFACE_HUB_CACHE，用于指定所有相关工具（transformers、datasets、hub 等）的根目录。

只要设置一次，所有模型、数据集、缓存都会自动存到你指定的路径。

---

🔧 Windows 设置步骤（图形界面）

1. 打开 控制面板 > 系统和安全 > 系统 > 高级系统设置
2. 点击右下角 环境变量
3. 在“用户变量”区域点击 新建
   • 变量名 1：HF_HOME

HF_HOME，变量值：G:\huggingface_cache（Hugging Face 缓存）；
      
   • 变量名 2：HUGGINGFACE_HUB_CACHE（可自定义路径）
     
     HUGGINGFACE_HUB_CACHE，变量值：G:\modelscope_cache（Hugging Face 缓存）；
4. 点击“确定”保存所有窗口

✅ 示例：

• 设置 HF_HOME = G:\huggingface_cache
• 设置 HUGGINGFACE_HUB_CACHE = G:\huggingface_cache
• 模型将下载到：G:\huggingface_cache\hub\models--xxx

---

📁 建议：提前创建目标文件夹

手动创建目录，避免路径不存在导致异常：

G:\huggingface_cache

或你更喜欢的位置，如：

E:\AI\models\huggingface_cache

---

🔄 重启终端或 IDE

设置完成后，必须重启你使用的工具，如：

• CMD / PowerShell
• PyCharm / VS Code
• Jupyter Notebook / Colab（本地运行时）

否则环境变量不会生效。

---

🧪 验证是否生效

🔧 第一步：前置准备（安装库 + 登录账号 + 获取权限）：

## 🔧 第一步：前置准备（安装库 + 登录账号 + 获取权限）

要从 Hugging Face 下载模型，仅安装 `transformers` 是不够的。你需要以下三步准备：

### 1. 安装核心依赖库

```bash
# 必装：用于模型下载、登录、缓存管理
pip install huggingface_hub

# 按需安装：用于加载和推理
pip install transformers
pip install torch  # 或 tensorflow/jax

🔧 第二步： 运行以下 Python 代码，查看缓存路径：

#  python
from transformers import TRANSFORMERS_CACHE

print(TRANSFORMERS_CACHE)

如果输出类似：

D:\huggingface\hub

✅ 恭喜！你已成功更改缓存位置！

---

📌 小贴士

• HF_HOME 是最推荐的方式，一劳永逸。
• 它不仅影响 transformers，还影响 datasets、diffusers、huggingface_hub 等所有 Hugging Face 生态工具。
• 如果你只想改 transformers 的路径，也可以用 TRANSFORMERS_CACHE，但不如 HF_HOME 统一。
• • transformers 是 Hugging Face 提供的模型推理库（由 🤗 Team 开发）
  • 真正用于管理模型下载、登录、缓存的核心库是：huggingface_hub

---

🧹 清理旧缓存（释放C盘空间）

迁移成功后，可以删除旧缓存释放空间：

C:\Users\你的用户名\.cache\huggingface\

⚠️ 确保新路径已正常下载模型后再删除！

---

✅ 总结：两步搞定

1. 设置环境变量：
   • 变量名：HF_HOME、HUGGINGFACE_HUB_CACHE
   • 变量值：G:\huggingface_cache（或其他路径）
2. 重启终端或IDE

从此，Hugging Face 模型不再占用 C 盘！

---

📌 下期预告：

• 《Hugging Face 模型下载太慢？5 种加速方案》
• 《如何用代码指定模型下载路径？cache_dir 详解》
• 《私有模型下载失败？登录与 Token 全攻略》

关注我，不错过每一篇干货！

【笔记】解决部署国产AI Agent 开源项目 MiniMax-M1时 Hugging Face 模型下载缓存占满 C 盘问题：更改缓存位置全流程_minimax agent本地部署-CSDN博客