解决 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-8B

• HF_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 的大模型，实现稳定、可复现的模型管理流程。