Hugging Face CLI 使用笔记
安装
pip install huggingface_hub
基础命令
1. 下载整个模型
# 基本语法
huggingface-cli download 模型名称 --local-dir 保存路径
# 示例
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct --local-dir E:\models\Qwen
2. 常用参数
huggingface-cli download 模型名称 \
--local-dir 保存路径 \
--local-dir-use-symlinks False \ # 不使用符号链接，直接复制文件
--resume-download \ # 支持断点续传
--max-workers 4 # 并行下载线程数（默认8）
高级用法
3. 下载特定文件
# 只下载特定类型的文件
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct \
--include "*.safetensors" "*.json" "*.txt" \
--local-dir E:\models\Qwen
# 排除某些文件
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct \
--exclude "*.bin" "*.gguf" \
--local-dir E:\models\Qwen
4. 下载特定文件（单个）
# 下载单个文件
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct \
--include "config.json" \
--local-dir E:\models\Qwen
5. 查看模型信息
# 查看模型文件列表（不下载）
huggingface-cli scan-cache
# 查看已下载的模型
huggingface-cli scan-cache
常见模型下载示例
YOLO 模型
# YOLO26 分类模型
huggingface-cli download ultralytics/yolo26n-cls --local-dir ./models/yolo26n-cls
huggingface-cli download ultralytics/yolo26s-cls --local-dir ./models/yolo26s-cls
huggingface-cli download ultralytics/yolo26m-cls --local-dir ./models/yolo26m-cls
# YOLO26 检测模型
huggingface-cli download ultralytics/yolo26n --local-dir ./models/yolo26n
huggingface-cli download ultralytics/yolo26s --local-dir ./models/yolo26s
huggingface-cli download ultralytics/yolo26m --local-dir ./models/yolo26m
大语言模型
# Qwen 模型
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct --local-dir E:\models\Qwen
# Llama 模型
huggingface-cli download meta-llama/Llama-2-7b-hf --local-dir E:\models\Llama2
# BERT 模型
huggingface-cli download bert-base-uncased --local-dir E:\models\bert
镜像加速（国内用户）
方法 1：设置环境变量
# Windows CMD
set HF_ENDPOINT=https://hf-mirror.com
# Windows PowerShell
$env:HF_ENDPOINT="https://hf-mirror.com"
# Linux/Mac
export HF_ENDPOINT=https://hf-mirror.com
# 然后正常下载
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct --local-dir E:\models\Qwen
方法 2：永久设置（Windows）
# 添加到系统环境变量
setx HF_ENDPOINT https://hf-mirror.com
# 重启终端后生效
常用镜像站
# 官方（国外）
https://huggingface.co
# 国内镜像
https://hf-mirror.com
https://hf.co
登录认证（私有模型）
获取 Token
- 访问 https://huggingface.co/settings/tokens
- 创建新 Token（Read 权限即可）
- 复制 Token
登录
# 方法 1：交互式登录
huggingface-cli login
# 方法 2：直接传入 Token
huggingface-cli login --token hf_xxxxxxxxxxxxx
# 方法 3：环境变量
set HF_TOKEN=hf_xxxxxxxxxxxxx
下载私有模型
# 登录后可以下载私有模型
huggingface-cli download your-username/private-model --local-dir ./models/private
管理缓存
查看缓存
# 查看所有已下载的模型
huggingface-cli scan-cache
# 输出示例：
# REPO ID REPO TYPE SIZE ON DISK NB FILES
# Qwen/Qwen2.5-VL-7B-Instruct model 14.2G 8
# bert-base-uncased model 440M 5
清理缓存
# 删除特定模型缓存
huggingface-cli delete-cache
# 会显示交互式菜单，选择要删除的模型
缓存位置
# Windows
C:\Users\你的用户名\.cache\huggingface\hub
# Linux/Mac
~/.cache/huggingface/hub
实用技巧
1. 断点续传
# 下载中断后，再次运行相同命令会自动续传
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct \
--local-dir E:\models\Qwen \
--resume-download
2. 并行下载
# 增加并行线程数（默认8，可以设置更高）
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct \
--local-dir E:\models\Qwen \
--max-workers 16
3. 只下载模型权重
# 只下载 safetensors 文件（模型权重）
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct \
--include "*.safetensors" \
--local-dir E:\models\Qwen
4. 下载特定版本
# 下载特定 commit 或 tag
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct \
--revision main \
--local-dir E:\models\Qwen
# 下载特定 commit
huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct \
--revision abc123def \
--local-dir E:\models\Qwen
Python API 等效代码
下载整个模型
from huggingface_hub import snapshot_download
model_path = snapshot_download(
repo_id="Qwen/Qwen2.5-VL-7B-Instruct",
local_dir="E:/models/Qwen",
local_dir_use_symlinks=False,
resume_download=True,
max_workers=4
)
下载单个文件
from huggingface_hub import hf_hub_download
file_path = hf_hub_download(
repo_id="Qwen/Qwen2.5-VL-7B-Instruct",
filename="config.json",
local_dir="E:/models/Qwen"
)
带进度条
from huggingface_hub import snapshot_download
from tqdm import tqdm
model_path = snapshot_download(
repo_id="Qwen/Qwen2.5-VL-7B-Instruct",
local_dir="E:/models/Qwen",
local_dir_use_symlinks=False,
tqdm_class=tqdm
)
常见问题
1. 下载速度慢
解决方案：
- 使用国内镜像站
- 增加
--max-workers参数 - 检查网络连接
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download 模型名称 --local-dir 路径 --max-workers 16
2. 磁盘空间不足
解决方案：
- 只下载必要文件（使用
--include） - 删除不需要的模型缓存
# 只下载 safetensors 和配置文件
huggingface-cli download 模型名称 \
--include "*.safetensors" "*.json" \
--local-dir 路径
3. 权限错误
解决方案：
- 检查目标目录是否有写权限
- 使用管理员权限运行
# Windows：以管理员身份运行 PowerShell
# Linux/Mac：使用 sudo（不推荐）或修改目录权限
chmod 755 /path/to/models
4. 网络超时
解决方案：
- 使用
--resume-download断点续传 - 减少
--max-workers数量
huggingface-cli download 模型名称 \
--local-dir 路径 \
--resume-download \
--max-workers 2
批量下载脚本
Windows 批处理
@echo off
set HF_ENDPOINT=https://hf-mirror.com
echo 下载 YOLO26 模型...
huggingface-cli download ultralytics/yolo26n-cls --local-dir ./models/yolo26n-cls
huggingface-cli download ultralytics/yolo26s-cls --local-dir ./models/yolo26s-cls
huggingface-cli download ultralytics/yolo26m-cls --local-dir ./models/yolo26m-cls
echo 下载完成！
pause
Python 脚本
import subprocess
import os
# 设置镜像
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
models = [
('ultralytics/yolo26n-cls', './models/yolo26n-cls'),
('ultralytics/yolo26s-cls', './models/yolo26s-cls'),
('ultralytics/yolo26m-cls', './models/yolo26m-cls'),
]
for repo_id, local_dir in models:
print(f"下载 {repo_id}...")
cmd = [
'huggingface-cli', 'download',
repo_id,
'--local-dir', local_dir,
'--local-dir-use-symlinks', 'False',
'--resume-download'
]
subprocess.run(cmd)
print(f"✅ {repo_id} 下载完成\n")
快速参考
| 命令 | 说明 |
|---|---|
huggingface-cli download 模型名 --local-dir 路径 |
下载整个模型 |
--include "*.safetensors" |
只下载特定文件 |
--exclude "*.bin" |
排除特定文件 |
--resume-download |
断点续传 |
--max-workers 8 |
并行线程数 |
--local-dir-use-symlinks False |
不使用符号链接 |
huggingface-cli login |
登录账户 |
huggingface-cli scan-cache |
查看缓存 |
huggingface-cli delete-cache |
清理缓存 |
推荐配置
# 国内用户推荐配置
export HF_ENDPOINT=https://hf-mirror.com
# 下载命令模板
huggingface-cli download 模型名称 \
--local-dir 保存路径 \
--local-dir-use-symlinks False \
--resume-download \
--max-workers 8
最后更新: 2026-01-18
评论区