文章目录
- 解决 huggingface-cli: command not found问题
- 1. 问题描述
- 2. 解决方案
- 2.1 安装或更新 huggingface-hub
- 2.2 使用 hf 命令下载模型
- 2.3 总结
解决 huggingface-cli: command not found问题
本文主要介绍在使用huggingface-cli命令下载大模型（如 Qwen3-8B）时出现bash: huggingface-cli: command not found…的原因及解决方案，并提供可行操作步骤。
在使用大模型进行自然语言处理或机器学习任务时，模型的下载和管理是第一步也是关键环节。Hugging Face 提供了丰富的预训练模型资源，但在升级到 huggingface-hub 1.0.0 及以上版本后，原有的 huggingface-cli 命令已被废弃，直接使用会出现 bash: huggingface-cli: command not found 的报错。
本文将针对这一问题，详细介绍在不同系统下的解决方案，包括安装最新版本的 huggingface-hub、使用新的 hf download 命令下载模型，以及设置镜像源加速下载的步骤。通过本文的指导，读者可以顺利管理和下载大模型，避免因命令更新导致的中断和困扰。
1. 问题描述
在使用 Hugging Face 的 CLI 下载大模型时，例如执行如下命令：
huggingface-cli download Qwen/Qwen3-8B --resume-download --local-dir /home/ly/model/Qwen3-8B可能会出现如下错误：
bash: huggingface-cli: command not found说明：该问题不仅出现在 Qwen3-8B 模型下载过程中，其他大模型下载时同样可能遇到。
2. 解决方案
经过调研发现，从huggingface-hub 1.0.0版本开始，原来的huggingface-cli命令已经被废弃，模型下载方式有所调整，需要使用新的hf命令。
2.1 安装或更新 huggingface-hub
确保使用最新版本的huggingface-hub，可执行以下命令：
pipinstall-U huggingface_hub安装成功示意：
当看到Successfully installed huggingface_hub xxx（版本号大于 1.0.0）表示安装成功。
2.2 使用 hf 命令下载模型
新版本中使用hf download命令替代原先的huggingface-cli：
exportHF_ENDPOINT=https://hf-mirror.com hf download Qwen/Qwen3-8B --local-dir /home/ly/model/Qwen3-8BHF_ENDPOINT：Hugging Face 镜像地址，可加速模型下载。hf download第一个参数：模型名称或链接。--local-dir：本地存储路径。
执行示意：
2.3 总结
- 原来的
huggingface-cli命令已被废弃。 - 最新版本的
huggingface-hub使用hf download命令完成模型下载。 - 通过设置镜像源（
HF_ENDPOINT）可以提升下载速度。 - 本方案适用于 Windows、Linux、MacOS 等系统。
使用hf download后，即可正常下载 Hugging Face 上的大模型，无需依赖原有 CLI。
bash: huggingface-cli: command not found 错误的根本原因是 huggingface-hub 1.0.0 及以上版本废弃了原有的 huggingface-cli 命令。解决方案是通过升级或安装最新的 huggingface-hub，并使用新的 hf download 命令来下载模型，同时可设置镜像源（HF_ENDPOINT）加速下载。
这一问题提示我们，在使用第三方库进行大模型下载或管理时，应关注 库的版本变化和命令更新，避免依赖过时命令。通过使用最新命令，用户能够在 Windows、Linux 和 macOS 系统上顺利下载 Hugging Face 的大模型，实现稳定、可复现的模型管理流程。
