Hugging Face 怎麼下載模型：hf 命令行下載單個文件、指定目錄與受限模型申請

適用於誰

• 搜「hugging face 下載模型」「huggingface-cli 下載模型」「huggingface cli 下載到指定目錄」「下載單個文件」的人；
• 下載時遇到 401 / 403、提示需要申請權限，或者不知道文件下到哪裏去了的人。

本文根據 Hugging Face 官方文檔整理，資料核對於 2026-10-11。

先說明一個事實：huggingface.co 在中國大陸的網絡環境下通常無法直接訪問，本文不提供任何訪問方法；下面的步驟以你所在的網絡能正常打開官網為前提。許多國內團隊發佈的開源模型，發佈方同時會在魔搭社區（ModelScope）等平台提供官方下載，可以到模型的官方介紹頁查看。

結論先說

1. 命令行工具現在叫 hf。舊教學裏的 huggingface-cli download 對應現在的 hf download，登入命令是 hf auth login。
2. 最常用的三種寫法：下載整個倉庫、下載指定文件、用 --include 按通配符篩選。
3. 預設下載到緩存目錄（~/.cache/huggingface/hub），不是當前文件夾。想放到指定位置，加 --local-dir。
4. 只想要一個 GGUF 文件，就不要下整個倉庫。一個倉庫裏往往有十幾個量化版本，全下會佔用上百 GB。
5. 受限模型（gated model）要先在網頁上申請，申請只能在瀏覽器裏做，通過後再用令牌下載。

步驟

1. 網頁直接下載（文件少時最簡單）

打開模型頁面，切到 Files and versions（文件與版本）標籤，每個文件右側有下載按鈕。只需要一兩個文件（比如一個 .gguf）時，這樣最快。

2. 安裝 hf 命令行

官方推薦的獨立安裝方式：

bash
# macOS / Linux
curl -LsSf https://hf.co/cli/install.sh | bash

powershell
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

也可以用 pip 或 Homebrew：

bash
pip install -U "huggingface_hub"
brew install hf

裝好後執行 hf download --help 確認可用。

3. 下載

下載整個倉庫：

bash
hf download HuggingFaceH4/zephyr-7b-beta

下載指定的一個或幾個文件（倉庫名後面跟文件名）：

bash
hf download gpt2 config.json
hf download gpt2 config.json model.safetensors

按通配符篩選，例如只要 safetensors 文件、排除 fp16 版本（官方示例）：

bash
hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"

GGUF 倉庫裏只要某一個量化版本時，同樣用 --include：

bash
hf download 用戶名/某模型-GGUF --include "*Q4_K_M*.gguf" --local-dir ./models

下載到指定目錄：

bash
hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu

官方說明：使用 --local-dir 時，目標文件夾裏會生成一個 .cache/huggingface/ 目錄記錄元數據，再次執行同樣的命令時，已經是最新的文件不會重複下載。

先看看要下多少：加 --dry-run 只列出將要下載的文件，不真正下載。

下載數據集或 Space，加 --repo-type：

bash
hf download HuggingFaceH4/ultrachat_200k --repo-type dataset

指定版本，加 --revision（分支名、標籤或提交哈希）。

4. 登入與訪問令牌

公開模型不登入也能下。私有倉庫和受限模型需要令牌：

1. 登入官網，進入 Settings → Access Tokens，點 New token；
2. 選擇令牌類型。官方文檔列出三種：

• read：只讀，下載用這個就夠；
• write：在只讀基礎上可以推送內容；
• fine-grained：可以精確到某個模型或某個組織的權限，官方建議生產環境只用這一種；

1. 在終端登入：

bash
hf auth login

按提示粘貼令牌。也可以不登入，只在單條命令裏用 --token 傳入，或者設定環境變量 HF_TOKEN。

令牌等同於密碼：不要寫進代碼倉庫，不要發給別人。官方文檔說明，令牌泄露後應立即在 Access Tokens 頁面刪除或刷新。

5. 申請受限模型的訪問權限

有些模型開啟了訪問申請（官方稱 gated model），直接下載會被拒絕。官方文檔的流程：

1. 登入後在瀏覽器裏打開該模型頁面（申請只能在瀏覽器裏完成）；
2. 頁面會提示你同意把用戶名和電郵分享給模型作者，有的還要填寫額外資訊。官方建議盡量填完整，方便作者審核；
3. 點同意提交。之後有兩種情況：作者設定了自動批准的，立刻就能下載；需要人工審核的，要等作者處理；
4. 通過後，用已登入的命令行或帶令牌的腳本下載。

官方文檔提醒：模型作者對訪問權限有完全的控制權，可以隨時撤銷，包括已經批准過的申請。

6. 文件下到哪裏了，怎麼改

系統盤空間不夠，把 HF_HOME 指到別的盤；網絡慢、經常超時，把 HF_HUB_DOWNLOAD_TIMEOUT 調大。單次下載也可以用 --cache-dir 臨時指定緩存目錄。

常見問題

Q：huggingface-cli 命令還能用嗎？

官方文檔現在全部以 hf 為準。舊命令是否保留以你安裝的版本為準，新寫的腳本建議直接用 hf。

Q：下載中斷了要從頭來嗎？

重新執行同一條命令即可，已完成且是最新版本的文件會被跳過。

Q：報 401 或 403？

401 一般是沒登入或令牌無效，重新 hf auth login；403 常見於受限模型沒有申請或還沒批准，或者所在組織要求使用 fine-grained 令牌而你用的是 read / write 令牌。

Q：怎麼知道自己的下載速度正不正常？

官方提供了測速頁面 fast.hf.co，可以測到最近的邊緣節點的帶寬。

Q：下載的模型怎麼用？

GGUF 文件可以導入 Ollama（見《Ollama Modelfile 怎麼寫》）或 LM Studio（見《LM Studio怎麼用》）；safetensors 格式的模型一般配合 transformers、diffusers 等庫用代碼加載，模型頁面上的「Use in 某個庫」按鈕會給出示例代碼（按鈕名稱以頁面為準）。

Q：用 git clone 可以嗎？

可以。官方說明模型倉庫是基於 Xet 存儲的 Git 倉庫，需要先安裝 git-xet 再克隆。只是下載使用的話，hf download 更省事。

參考資料

• Hugging Face 文檔：Downloading models — https://huggingface.co/docs/hub/models-downloading
• huggingface_hub 文檔：Command Line Interface — https://huggingface.co/docs/huggingface_hub/guides/cli
• Gated models — https://huggingface.co/docs/hub/models-gated
• User access tokens — https://huggingface.co/docs/hub/security-tokens
• Environment variables — https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables