Hub Python 庫文件
命令列介面 (CLI)
並獲得增強的文件體驗
開始使用
命令列介面 (CLI)
huggingface_hub Python 包自帶了一個名為 hf 的內建 CLI。這個工具允許您直接從終端與 Hugging Face Hub 進行互動。例如，您可以登入您的賬戶，建立倉庫，上傳和下載檔案等。它還提供了一些方便的功能來配置您的機器或管理您的快取。在本指南中，我們將介紹 CLI 的主要功能以及如何使用它們。
本指南涵蓋了
hfCLI 的 most important features。有關所有命令和選項的完整參考，請參閱 CLI 參考。
入門
獨立安裝程式 (推薦)
您可以透過一個命令安裝 hf CLI
在 macOS 和 Linux 上
>>> curl -LsSf https://huggingface.co/cli/install.sh | bash
在 Windows 上
>>> powershell -ExecutionPolicy ByPass -c "irm https://huggingface.co/cli/install.ps1 | iex"安裝完成後，您可以檢查 CLI 是否已正確設定
>>> hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...
Hugging Face Hub CLI
Options:
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or
customize the installation.
--help Show this message and exit.
Commands:
auth Manage authentication (login, logout, etc.).
cache Manage local cache directory.
datasets Interact with datasets on the Hub.
download Download files from the Hub.
endpoints Manage Hugging Face Inference Endpoints.
env Print information about the environment.
jobs Run and manage Jobs on the Hub.
models Interact with models on the Hub.
repo Manage repos on the Hub.
repo-files Manage files in a repo on the Hub.
spaces Interact with spaces on the Hub.
upload Upload a file or a folder to the Hub.
upload-large-folder Upload a large folder to the Hub.
version Print information about the hf version.如果 CLI 已正確安裝，您應該會看到 CLI 中所有可用選項的列表。如果您收到類似 command not found: hf 的錯誤訊息，請參閱 安裝 指南。
--help選項對於獲取命令的更多詳細資訊非常方便。您可以隨時使用它來列出所有可用的選項及其詳細資訊。例如，hf upload --help提供了有關如何使用 CLI 上傳檔案的更多資訊。
使用 uv
使用 hf CLI 的最簡單方法是使用 uvx。它始終在一個隔離的環境中執行最新版本 — 無需安裝！
首先確保已安裝 uv。有關說明，請參閱 uv 安裝指南。
然後直接使用 CLI
>>> uvx hf auth login >>> uvx hf download >>> uvx hf ...
uvx hf使用hfPyPI 包。
使用 pip 安裝
CLI 也隨核心 huggingface_hub 包一起提供
>>> pip install -U "huggingface_hub"使用 Homebrew
您也可以使用 Homebrew 安裝 CLI
>>> brew install huggingface-cli
在此處檢視 Homebrew huggingface 頁面 瞭解更多詳情。
hf auth login
在很多情況下，您必須登入 Hugging Face 賬戶才能與 Hub 互動（下載私有倉庫，上傳檔案，建立 PR 等）。為此，您需要從您的 設定頁面獲取一個 使用者訪問令牌。使用者訪問令牌用於向 Hub 驗證您的身份。如果您想上傳或修改內容，請確保設定一個具有寫入許可權的令牌。
獲得令牌後，在終端中執行以下命令
>>> hf auth login
此命令將提示您輸入令牌。複製貼上您的令牌並按 Enter。然後，您將被問及是否也應將令牌儲存為 git 憑據。如果您打算在本地使用 git，請再次按 Enter（預設為“是”）。最後，它將呼叫 Hub 來檢查您的令牌是否有效，並將其本地儲存。
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_|
_| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _| _| _|_| _|_|_| _|_|_|_| _| _|_|_|
_| _| _| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_| _| _|_| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _| _| _| _|_|_| _|_|_|_|
To log in, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens .
Enter your token (input will not be visible):
Add token as git credential? (Y/n)
Token is valid (permission: write).
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful或者，如果您想在不被提示的情況下登入，您可以直接從命令列傳遞令牌。為了更安全，我們建議將令牌作為環境變數傳遞，以避免將其貼上到命令歷史記錄中。
# Or using an environment variable
>>> hf auth login --token $HF_TOKEN --add-to-git-credential
Token is valid (permission: write).
The token `token_name` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful
The current active token is: `token_name`有關身份驗證的更多詳細資訊，請檢視此部分。
hf auth whoami
如果您想知道是否已登入，可以使用 hf auth whoami。此命令沒有任何選項，僅列印您的使用者名稱以及您在 Hub 上所屬的組織。
hf auth whoami
Wauplin
orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster如果您未登入，將列印錯誤訊息。
hf auth logout
此命令將登出您的操作。實際上，它將刪除您計算機上儲存的所有令牌。如果您想刪除特定的令牌，可以將其作為引數指定。
如果您使用 HF_TOKEN 環境變數登入（請參閱 參考），此命令將不會登出您。如果是這種情況，您必須在計算機配置中取消設定環境變數。
hf download
使用 hf download 命令直接從 Hub 下載檔案。在內部，它使用與 下載 指南中描述的 hf_hub_download() 和 snapshot_download() 相同的助手，並將返回的路徑列印到終端。在下面的示例中，我們將介紹最常見的用例。有關可用選項的完整列表，您可以執行
hf download --help下載單個檔案
要從倉庫下載單個檔案，只需按以下方式提供 repo_id 和檔名
>>> hf download gpt2 config.json downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/wauplin/.cache/huggingface/hub/tmpwrq8dm5o (…)ingface.co/gpt2/resolve/main/config.json: 100%|██████████████████████████████████| 665/665 [00:00<00:00, 2.49MB/s] /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json
命令將始終在最後一行列印本地檔案的路徑。
要下載位於倉庫子目錄中的檔案，您應以 posix 格式提供倉庫中檔案的路徑，如下所示
>>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensors
下載整個倉庫
在某些情況下，您只想下載倉庫中的所有檔案。這可以透過僅指定 repo id 來完成
>>> hf download HuggingFaceH4/zephyr-7b-beta Fetching 23 files: 0%| | 0/23 [00:00<?, ?it/s] ... ... /home/wauplin/.cache/huggingface/hub/models--HuggingFaceH4--zephyr-7b-beta/snapshots/3bac358730f8806e5c3dc7c7e19eb36e045bf720
下載多個檔案
您也可以使用單個命令下載倉庫中的一部分檔案。這可以透過兩種方式完成。如果您已經有了要下載檔案的精確列表，您可以按順序提供它們
>>> hf download gpt2 config.json model.safetensors Fetching 2 files: 0%| | 0/2 [00:00<?, ?it/s] downloading https://huggingface.co/gpt2/resolve/11c5a3d5811f50298f278a704980280950aedb10/model.safetensors to /home/wauplin/.cache/huggingface/hub/tmpdachpl3o (…)8f278a7049802950aedb10/model.safetensors: 100%|██████████████████████████████| 8.09k/8.09k [00:00<00:00, 40.5MB/s] Fetching 2 files: 100%|████████████████████████████████████████████████████████████████| 2/2 [00:00<00:00, 3.76it/s] /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10
另一種方法是提供模式以使用 --include 和 --exclude 過濾要下載的檔案。例如，如果您想從 stabilityai/stable-diffusion-xl-base-1.0 下載所有 safetensors 檔案，但排除 FP16 精度的檔案
>>> hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"*
Fetching 8 files: 0%| | 0/8 [00:00<?, ?it/s]
...
...
Fetching 8 files: 100%|█████████████████████████████████████████████████████████████████████████| 8/8 (...)
/home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7b下載資料集或 Space
上面的示例展示瞭如何從模型倉庫下載。要下載資料集或 Space，請使用 --repo-type 選項
# https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k
>>> hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat
>>> hf download HuggingFaceH4/zephyr-chat --repo-type space
...下載特定修訂版本
上面的示例演示瞭如何從主分支上的最新提交下載。要從特定修訂版本（提交雜湊、分支名稱或標籤）下載，請使用 --revision 選項
>>> hf download bigcode/the-stack --repo-type dataset --revision v1.1 ...
下載到本地資料夾
推薦的（也是預設的）從 Hub 下載檔案的方式是使用快取系統。但是，在某些情況下，您想下載檔案並將它們移動到特定資料夾。這對於使工作流程更接近 git 命令提供的功能很有用。您可以使用 --local-dir 選項來完成此操作。
在本地目錄的根目錄下會建立一個 .cache/huggingface/ 資料夾，其中包含下載檔案的元資料。這可以防止在檔案已更新時重新下載。如果元資料發生更改，則會下載新版本的檔案。這使得 local-dir 最佳化為僅拉取最新更改。
有關下載到本地檔案的更多詳細資訊，請檢視 下載 指南。
>>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu ... fuyu/model-00001-of-00002.safetensors
試執行模式
在某些情況下，您想在實際下載檔案之前檢查將要下載哪些檔案。您可以使用 --dry-run 引數來檢查。它會列出倉庫中所有要下載的檔案，並檢查它們是否已經下載。這可以讓人瞭解有多少檔案需要下載以及它們的大小。
>>> hf download openai-community/gpt2 --dry-run [dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00, 6.26it/s] [dry-run] Will download 11 files (out of 26) totalling 5.6G. File Bytes to download --------------------------------- ----------------- .gitattributes - 64-8bits.tflite 125.2M 64-fp16.tflite 248.3M 64.tflite 495.8M README.md - config.json - flax_model.msgpack 497.8M generation_config.json - merges.txt - model.safetensors 548.1M onnx/config.json - onnx/decoder_model.onnx 653.7M onnx/decoder_model_merged.onnx 655.2M onnx/decoder_with_past_model.onnx 653.7M onnx/generation_config.json - onnx/merges.txt - onnx/special_tokens_map.json - onnx/tokenizer.json - onnx/tokenizer_config.json - onnx/vocab.json - pytorch_model.bin 548.1M rust_model.ot 702.5M tf_model.h5 497.9M tokenizer.json - tokenizer_config.json - vocab.json -
有關更多詳細資訊，請參閱 下載指南。
指定快取目錄
如果不使用 --local-dir，所有檔案將預設下載到由 HF_HOME 環境變數定義的快取目錄。您可以使用 --cache-dir 指定自定義快取
>>> hf download adept/fuyu-8b --cache-dir ./path/to/cache ... ./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745
指定令牌
要訪問私有或受限倉庫，您必須使用令牌。預設情況下，將使用本地儲存的令牌（使用 hf auth login）。如果您想顯式進行身份驗證，請使用 --token 選項
>>> hf download gpt2 config.json --token=hf_**** /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json
靜默模式
預設情況下，hf download 命令會非常詳細。它會列印警告資訊、下載檔案的資訊以及進度條等詳細內容。如果您想遮蔽所有這些資訊，請使用 --quiet 選項。此時只會列印最後一行（即下載檔案的路徑）。如果您想在指令碼中將輸出傳遞給另一個命令，這一點會非常有用。
>>> hf download gpt2 --quiet /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10
下載超時
在連線速度慢的機器上，您可能會遇到類似以下的超時問題
`httpx.TimeoutException: (TimeoutException("HTTPSConnectionPool(host='cdn-lfs-us-1.huggingface.co', port=443): Read timed out. (read timeout=10)"), '(Request ID: a33d910c-84c6-4514-8362-c705e2039d38)')`為了解決這個問題，您可以將 HF_HUB_DOWNLOAD_TIMEOUT 環境變數設定為一個更高的值（預設值為 10）
export HF_HUB_DOWNLOAD_TIMEOUT=30更多詳情，請檢視 環境變數參考。然後重新執行您的下載命令。
hf upload
使用 hf upload 命令可以直接將檔案上傳到 Hub。內部實現使用了 upload_file() 和 upload_folder() 輔助函式，這些函式在 上傳 指南中有所描述。在下面的示例中，我們將介紹最常見的用例。要檢視所有可用選項，您可以執行
>>> hf upload --help上傳整個資料夾
此命令的預設用法是
# Usage: hf upload [repo_id] [local_path] [path_in_repo]要上傳倉庫根目錄下的當前目錄，請使用
>>> hf upload my-cool-model . . https://huggingface.co/Wauplin/my-cool-model/tree/main/
如果倉庫尚不存在，它將被自動建立。
您也可以上傳一個特定的資料夾
>>> hf upload my-cool-model ./models . https://huggingface.co/Wauplin/my-cool-model/tree/main/
最後，您可以將資料夾上傳到倉庫中的特定目標位置
>>> hf upload my-cool-model ./path/to/curated/data /data/train https://huggingface.co/Wauplin/my-cool-model/tree/main/data/train
上傳單個檔案
您也可以透過設定 local_path 指向您本地檔案來上傳單個檔案。在這種情況下，path_in_repo 是可選的，預設將使用您本地檔案的名稱
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors
如果您想將單個檔案上傳到倉庫中的特定目錄，請相應地設定 path_in_repo
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensors
上傳多個檔案
要一次性上傳一個資料夾中的多個檔案而不上傳整個資料夾，請使用 --include 和 --exclude 模式。它還可以與 --delete 選項結合使用，在上傳新檔案時刪除倉庫中的舊檔案。在下面的示例中，我們透過刪除遠端檔案並上傳除 /logs 之外的所有檔案來同步本地 Space
# Sync local Space with Hub (upload new files except from logs/, delete removed files)
>>> hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
...上傳到資料集或 Space
要上傳到資料集或 Space，請使用 --repo-type 選項
>>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset ...
上傳到組織
要上傳到某個組織擁有的倉庫，而不是個人倉庫，您必須在 repo_id 中明確指定它
>>> hf upload MyCoolOrganization/my-cool-model . . https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/
上傳到特定修訂版本
預設情況下，檔案將上傳到 main 分支。如果您想將檔案上傳到另一個分支或引用，請使用 --revision 選項
# Upload files to a PR
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...注意： 如果 revision 不存在且未設定 --create-pr，則會自動從 main 分支建立一個新分支。
上傳並建立 PR
如果您沒有許可權推送到倉庫，您必須開啟一個 PR，並告知作者您想進行的更改。這可以透過設定 --create-pr 選項來完成
# Create a PR and upload the files to it
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/定期上傳
在某些情況下，您可能希望定期推送更新到倉庫。例如，如果您正在訓練一個模型，並且希望每 10 分鐘上傳一次日誌資料夾，這會很有用。您可以使用 --every 選項來實現此目的
# Upload new logs every 10 minutes
hf upload training-model logs/ --every=10指定提交訊息
使用 --commit-message 和 --commit-description 為您的提交設定自定義訊息和描述，而不是使用預設的
>>> hf upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details."
...
https://huggingface.co/Wauplin/my-cool-model/tree/main指定令牌
要上傳檔案，您必須使用令牌。預設情況下，將使用本地儲存的令牌（透過 hf auth login 儲存）。如果您想顯式進行身份驗證，請使用 --token 選項
>>> hf upload Wauplin/my-cool-model ./models . --token=hf_**** ... https://huggingface.co/Wauplin/my-cool-model/tree/main
靜默模式
預設情況下，hf upload 命令會非常詳細。它會列印警告資訊、上傳檔案的資訊以及進度條等詳細內容。如果您想遮蔽所有這些資訊，請使用 --quiet 選項。此時只會列印最後一行（即上傳檔案的 URL）。如果您想在指令碼中將輸出傳遞給另一個命令，這一點會非常有用。
>>> hf upload Wauplin/my-cool-model ./models . --quiet https://huggingface.co/Wauplin/my-cool-model/tree/main
hf upload-large-folder
使用 hf upload-large-folder 將非常大的資料夾（數百 GB 甚至 TB）上傳到 Hub。此命令針對可恢復上傳進行了最佳化，並能優雅地處理故障。
# Upload a large folder to a model repository
>>> hf upload-large-folder Wauplin/my-cool-model ./large_model_dir
# Upload to a specific revision
>>> hf upload-large-folder Wauplin/my-cool-model ./large_model_dir --revision v1.0
# Upload a dataset
>>> hf upload-large-folder Wauplin/my-cool-dataset ./large_data_dir --repo-type dataset該命令會自動
- 將大檔案分割成塊以實現可靠上傳
- 從中斷處恢復上傳
- 優雅地處理網路故障
當您有非常大的檔案或資料夾，可能需要很長時間才能上傳時，請使用
hf upload-large-folder。對於較小的上傳，請首選hf upload。
hf models
使用 hf models 列出 Hub 上的模型並獲取特定模型的詳細資訊。
列出模型
# List trending models
>>> hf models ls
# Search for models
>>> hf models ls --search "lora"
# Filter by author
>>> hf models ls --author Qwen
# Sort by downloads
>>> hf models ls --sort downloads --limit 10獲取模型資訊
>>> hf models info Lightricks/LTX-2
使用 --expand 來獲取額外的屬性，如 downloads、likes、tags 等。
hf datasets
使用 hf datasets 列出 Hub 上的資料集並獲取特定資料集的詳細資訊。
列出資料集
# List trending datasets
>>> hf datasets ls
# Search for datasets
>>> hf datasets ls --search "code"
# Sort by downloads
>>> hf datasets ls --sort downloads --limit 10獲取資料集資訊
>>> hf datasets info HuggingFaceFW/fineweb
hf spaces
使用 hf spaces 列出 Hub 上的 Space 並獲取特定 Space 的詳細資訊。
列出 Space
# List trending Spaces
>>> hf spaces ls
# Search for Spaces
>>> hf spaces ls --search "3d"
# Sort by likes
>>> hf spaces ls --sort likes --limit 10獲取 Space 資訊
>>> hf spaces info enzostvs/deepsite
hf papers
使用 hf papers 列出 Hub 上的每日論文。
列出論文
# List most recent daily papers
>>> hf papers ls
# List trending papers
>>> hf papers ls --sort=trending
# List papers from a specific date
>>> hf papers ls --date=2025-01-23
# List today's papers
>>> hf papers ls --date=today
# Limit results
>>> hf papers ls --sort=trending --limit=5hf repo
hf repo 允許您在 Hugging Face Hub 上建立、刪除、移動倉庫以及更新其設定。它還包括用於管理分支和標籤的子命令。
建立倉庫
>>> hf repo create Wauplin/my-cool-model Successfully created Wauplin/my-cool-model on the Hub. Your repo is now available at https://huggingface.co/Wauplin/my-cool-model
建立私有資料集或 Space
>>> hf repo create my-cool-dataset --repo-type dataset --private >>> hf repo create my-gradio-space --repo-type space --space-sdk gradio
如果倉庫可能已存在，請使用 --exist-ok；使用 --resource-group-id 來定位企業資源組。
刪除倉庫
>>> hf repo delete Wauplin/my-cool-model
資料集和 Space
>>> hf repo delete my-cool-dataset --repo-type dataset >>> hf repo delete my-gradio-space --repo-type space
移動倉庫
>>> hf repo move old-namespace/my-model new-namespace/my-model
更新倉庫設定
>>> hf repo settings Wauplin/my-cool-model --gated auto
>>> hf repo settings Wauplin/my-cool-model --private true
>>> hf repo settings Wauplin/my-cool-model --private false--gated：可選值包括auto、manual、false--private true|false：設定倉庫隱私
hf repo branch
使用 hf repo branch 在 Hub 上為倉庫建立和刪除分支。
# Create a branch
>>> hf repo branch create Wauplin/my-cool-model dev
# Create a branch from a specific revision
>>> hf repo branch create Wauplin/my-cool-model release-1 --revision refs/pr/104
# Delete a branch
>>> hf repo branch delete Wauplin/my-cool-model dev所有命令都接受
--repo-type（可選值包括model、dataset、space）和--token（如果您需要顯式進行身份驗證）。使用任何命令的--help來檢視所有選項。
hf repo-files
如果您想從 Hugging Face 倉庫中刪除檔案，請使用 hf repo-files 命令。
刪除檔案
hf repo-files delete <repo_id> 子命令允許您從倉庫中刪除檔案。以下是一些使用示例。
刪除資料夾
>>> hf repo-files delete Wauplin/my-cool-model folder/ Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...
刪除多個檔案
>>> hf repo-files delete Wauplin/my-cool-model file.txt folder/pytorch_model.bin Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...
使用萬用字元模式刪除檔案集。模式是標準的萬用字元（globbing 模式），記錄在此 處。模式匹配基於 fnmatch。
請注意，與傳統的 Unix shell globbing 不同，
fnmatch會跨路徑邊界匹配*。例如，"data/*.json"將同時匹配data/file.json和data/subdir/file.json。要僅匹配當前目錄中的檔案，您需要單獨列出它們或使用更具體的模式。
>>> hf repo-files delete Wauplin/my-cool-model "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...指定令牌
要刪除倉庫中的檔案，您必須經過身份驗證並獲得授權。預設情況下，將使用本地儲存的令牌（透過 hf auth login 儲存）。如果您想顯式進行身份驗證，請使用 --token 選項
>>> hf repo-files delete --token=hf_**** Wauplin/my-cool-model file.txt
hf cache
使用 hf cache 管理您的本地 Hugging Face 快取目錄。快取儲存從 Hub 下載的模型、資料集和其他檔案。
# List cached repositories
>>> hf cache ls
# List cached revisions
>>> hf cache ls --revisions
# Remove specific items from cache
>>> hf cache rm model/gpt2
# Remove unreferenced revisions
>>> hf cache prune
# Verify cached file checksums
>>> hf cache verify gpt2hf cache ls
使用 hf cache ls 來檢查您的 Hugging Face 快取本地儲存了什麼。預設情況下，它會按倉庫聚合資訊
>>> hf cache ls
ID SIZE LAST_ACCESSED LAST_MODIFIED REFS
--------------------------- -------- ------------- ------------- -----------
dataset/nyu-mll/glue 157.4M 2 days ago 2 days ago main script
model/LiquidAI/LFM2-VL-1.6B 3.2G 4 days ago 4 days ago main
model/microsoft/UserLM-8b 32.1G 4 days ago 4 days ago main
Found 3 repo(s) for a total of 5 revision(s) and 35.5G on disk.新增 --revisions 來深入瞭解特定的快照，並連結過濾器來聚焦於重要內容
>>> hf cache ls --filter "size>30g" --revisions
ID REVISION SIZE LAST_MODIFIED REFS
------------------------- ---------------------------------------- -------- ------------- ----
model/microsoft/UserLM-8b be8f2069189bdf443e554c24e488ff3ff6952691 32.1G 4 days ago main
Found 1 repo(s) for a total of 1 revision(s) and 32.1G on disk.該命令支援多種指令碼輸出格式：--format json 列印結構化物件，--format csv 寫入逗號分隔的行，而 --quiet 只打印 ID。使用 --sort 按 accessed、modified、name 或 size 對條目進行排序（附加 :asc 或 :desc 來控制順序），並使用 --limit 將結果限制為前 N 個條目。將這些與 --cache-dir 結合使用來定位備用快取位置。有關高階工作流程，請參閱 管理您的快取 指南。
透過將 ID 管道傳輸到 hf cache rm 來刪除使用 hf cache ls --q 選擇的快取條目
>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y
About to delete 2 repo(s) totalling 5.31G.
- model/meta-llama/Llama-3.2-1B-Instruct (entire repo)
- model/hexgrad/Kokoro-82M (entire repo)
Delete repo: ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct
Delete repo: ~/.cache/huggingface/hub/models--hexgrad--Kokoro-82M
Cache deletion done. Saved 5.31G.
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.hf cache rm
hf cache rm 刪除快取的倉庫或單個修訂版本。傳遞一個或多個倉庫 ID（model/bert-base-uncased）或修訂版本雜湊
>>> hf cache rm model/LiquidAI/LFM2-VL-1.6B
About to delete 1 repo(s) totalling 3.2G.
- model/LiquidAI/LFM2-VL-1.6B (entire repo)
Proceed with deletion? [y/N]: y
Delete repo: ~/.cache/huggingface/hub/models--LiquidAI--LFM2-VL-1.6B
Cache deletion done. Saved 3.2G.
Deleted 1 repo(s) and 2 revision(s); freed 3.2G.在同一呼叫中混合使用倉庫和特定修訂版本。使用 --dry-run 預覽影響，或使用 --yes 跳過確認提示 — 這在自動化指令碼中非常有用
>>> hf cache rm model/t5-small 8f3ad1c --dry-run
About to delete 1 repo(s) and 1 revision(s) totalling 1.1G.
- model/t5-small:
8f3ad1c [main] 1.1G
Dry run: no files were deleted.在預設快取位置之外工作時，將該命令與 --cache-dir PATH 配對。
hf cache prune
hf cache prune 是一個方便的快捷方式，它會刪除快取中所有未引用（detached）的修訂版本。這樣只保留仍然可以透過分支或標籤訪問的修訂版本
>>> hf cache prune
About to delete 3 unreferenced revision(s) (2.4G total).
- model/t5-small:
1c610f6b [refs/pr/1] 820.1M
d4ec9b72 [(detached)] 640.5M
- dataset/google/fleurs:
2b91c8dd [(detached)] 937.6M
Proceed? [y/N]: y
Deleted 3 unreferenced revision(s); freed 2.4G.與其它快取命令一樣，--dry-run、--yes 和 --cache-dir 都可用。有關更多示例，請參閱 管理您的快取 指南。
hf cache verify
使用 hf cache verify 來驗證本地檔案與 Hub 上的校驗和。您可以驗證快取快照或常規的本地目錄。
示例
# Verify main revision of a model in cache
>>> hf cache verify deepseek-ai/DeepSeek-OCR
# Verify a specific revision
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision refs/pr/5
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision ef93bf4a377c5d5ed9dca78e0bc4ea50b26fe6a4
# Verify a private repo
>>> hf cache verify me/private-model --token hf_***
# Verify a dataset
>>> hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset
# Verify files in a local directory
>>> hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repo預設情況下，該命令會警告缺失或多餘的檔案。使用標誌將這些警告變成錯誤
>>> hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-files
成功時，您將看到一個摘要
✅ Verified 13 file(s) for 'deepseek-ai/DeepSeek-OCR' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6 All checksums match.
如果檢測到不匹配，該命令將列印詳細列表並以非零狀態退出。
hf repo tag
使用 hf repo tag 來建立、列出和刪除 Hub 上的倉庫標籤。
# Create a tag
>>> hf repo tag create my-model v1.0
# List tags
>>> hf repo tag list my-model
# Delete a tag
>>> hf repo tag delete my-model v1.0給模型打標籤
要給倉庫打標籤，您需要提供 repo_id 和 tag 名稱
>>> hf repo tag create Wauplin/my-cool-model v1.0 You are about to create tag v1.0 on model Wauplin/my-cool-model Tag v1.0 created on Wauplin/my-cool-model
在特定修訂版本上給模型打標籤
如果您想給特定修訂版本打標籤，可以使用 --revision 選項。預設情況下，標籤將建立在 main 分支上
>>> hf repo tag create Wauplin/my-cool-model v1.0 --revision refs/pr/104 You are about to create tag v1.0 on model Wauplin/my-cool-model Tag v1.0 created on Wauplin/my-cool-model
給資料集或 Space 打標籤
如果您想給資料集或 Space 打標籤，則必須指定 --repo-type 選項
>>> hf repo tag create bigcode/the-stack v1.0 --repo-type dataset You are about to create tag v1.0 on dataset bigcode/the-stack Tag v1.0 created on bigcode/the-stack
列出標籤
要列出倉庫的所有標籤，請使用 -l 或 --list 選項
>>> hf repo tag create Wauplin/gradio-space-ci -l --repo-type space
Tags for space Wauplin/gradio-space-ci:
0.2.2
0.2.1
0.2.0
0.1.2
0.0.2
0.0.1刪除標籤
要刪除標籤，請使用 -d 或 --delete 選項
>>> hf repo tag create -d Wauplin/my-cool-model v1.0 You are about to delete tag v1.0 on model Wauplin/my-cool-model Proceed? [Y/n] y Tag v1.0 deleted on Wauplin/my-cool-model
您也可以傳遞 -y 來跳過確認步驟。
hf env
hf env 命令列印有關您的機器設定的詳細資訊。當您在 GitHub 上開啟一個 issue 時，這對於幫助維護者調查您的問題很有用。
>>> hf env
Copy-and-paste the text below in your GitHub issue.
- huggingface_hub version: 1.0.0.rc6
- Platform: Linux-6.8.0-85-generic-x86_64-with-glibc2.35
- Python version: 3.11.14
- Running in iPython ?: No
- Running in notebook ?: No
- Running in Google Colab ?: No
- Running in Google Colab Enterprise ?: No
- Token path ?: /home/wauplin/.cache/huggingface/token
- Has saved token ?: True
- Who am I ?: Wauplin
- Configured git credential helpers: store
- Installation method: unknown
- Torch: N/A
- httpx: 0.28.1
- hf_xet: 1.1.10
- gradio: 5.41.1
- tensorboard: N/A
- pydantic: 2.11.7
- ENDPOINT: https://huggingface.co
- HF_HUB_CACHE: /home/wauplin/.cache/huggingface/hub
- HF_ASSETS_CACHE: /home/wauplin/.cache/huggingface/assets
- HF_TOKEN_PATH: /home/wauplin/.cache/huggingface/token
- HF_STORED_TOKENS_PATH: /home/wauplin/.cache/huggingface/stored_tokens
- HF_HUB_OFFLINE: False
- HF_HUB_DISABLE_TELEMETRY: False
- HF_HUB_DISABLE_PROGRESS_BARS: None
- HF_HUB_DISABLE_SYMLINKS_WARNING: False
- HF_HUB_DISABLE_EXPERIMENTAL_WARNING: False
- HF_HUB_DISABLE_IMPLICIT_TOKEN: False
- HF_HUB_DISABLE_XET: False
- HF_HUB_ETAG_TIMEOUT: 10
- HF_HUB_DOWNLOAD_TIMEOUT: 10hf jobs
使用熟悉的類 Docker 介面在 Hugging Face 基礎設施上執行計算作業。
hf jobs 是一個命令列工具，讓您可以使用簡單的命令在 Hugging Face 的基礎設施（包括 GPU 和 TPU！）上執行任何東西。將其想象成 docker run，但用於在 A100 上執行程式碼。
# Directly run Python code
>>> hf jobs run python:3.12 python -c 'print("Hello from the cloud!")'
# Use GPUs without any setup
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c "import torch; print(torch.cuda.get_device_name())"
# Run in an organization account
>>> hf jobs run --namespace my-org-name python:3.12 python -c 'print("Running in an org account")'
# Run from Hugging Face Spaces
>>> hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c 'select "hello world"'
# Run a Python script with `uv` (experimental)
>>> hf jobs uv run my_script.py✨ 主要功能
- 🐳 類似 Docker 的 CLI：熟悉的命令（
run、ps、logs、inspect）來執行和管理作業 - 🔥 任何硬體：從 CPU 到 A100 GPU 和 TPU Pod - 只需一個簡單的標誌即可切換
- 📦 執行任何東西：使用 Docker 映象、HF Spaces 或您的自定義容器
- 🔐 簡單的身份驗證：只需使用您的 HF 令牌
- 📊 即時監控：即時流式傳輸日誌，就像在本地執行一樣
- 💰 按需付費：只為使用的秒數付費
Hugging Face 作業僅對 Pro 使用者和 Team 或 Enterprise 組織可用。升級您的計劃即可開始！
快速開始
1. 執行您的第一個作業
# Run a simple Python script
>>> hf jobs run python:3.12 python -c 'print("Hello from HF compute!")'此命令將執行作業並顯示日誌。您可以傳遞 --detach 將作業置於後臺執行，並且只打印作業 ID。
2. 檢查作業狀態
# List your running jobs
>>> hf jobs ps
# List all jobs
>>> hf jobs ps -a
# Inspect the status of a job
>>> hf jobs inspect <job_id>
# View logs from a job
>>> hf jobs logs <job_id>
# View resources usage stats and metrics of running jobs
>>> hf jobs stats
# View resources usage stats and metrics of some jobs
>>> hf jobs stats [job_ids]...
# Cancel a job
>>> hf jobs cancel <job_id>3. 在 GPU 上執行
您還可以使用 --flavor 選項在 GPU 或 TPU 上執行作業。例如，要在 A10G GPU 上執行 PyTorch 作業
# Use an A10G GPU to check PyTorch CUDA
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'執行此命令將顯示以下輸出！
This code ran with the following GPU: NVIDIA A10G
可以使用 -- 來分隔命令和作業選項，以提高畫質晰度，例如 hf jobs run --flavor a10g-small -- python -c '...'
就這樣！您現在可以在 Hugging Face 的基礎設施上執行程式碼了。
常見用例
- 模型訓練：在 GPU 上進行微調或訓練模型（T4、A10G、A100），無需管理基礎設施
- 合成數據生成：在強大硬體上使用 LLM 生成大規模資料集
- 資料處理：使用高 CPU 配置處理海量資料集，用於並行工作負載
- 批次推理：使用最佳化的 GPU 設定對數千個樣本進行離線推理
- 實驗和基準測試：在一致的硬體上執行 ML 實驗以獲得可復現的結果
- 開發和除錯：在沒有本地 CUDA 設定的情況下測試 GPU 程式碼
傳遞環境變數和秘密
您可以使用以下方式將環境變數傳遞給您的作業
# Pass environment variables
>>> hf jobs run -e FOO=foo -e BAR=bar python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'# Pass an environment from a local .env file
>>> hf jobs run --env-file .env python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'# Pass secrets - they will be encrypted server side
>>> hf jobs run -s MY_SECRET=psswrd python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'# Pass secrets from a local .env.secrets file - they will be encrypted server side
>>> hf jobs run --secrets-file .env.secrets python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'使用
--secrets HF_TOKEN來隱式傳遞您本地的 Hugging Face 令牌。使用這種語法，秘密將從環境變數中檢索。對於HF_TOKEN，如果環境變數未設定，它可能會讀取 Hugging Face 主資料夾中的令牌檔案。
作業超時
作業預設超時時間為 30 分鐘，之後會自動停止。對於模型訓練等長時間執行的任務，請使用 --timeout 選項設定自定義超時
# Set timeout in seconds (default unit)
>>> hf jobs run --timeout 7200 python:3.12 python train.py
# Use time units: s (seconds), m (minutes), h (hours), d (days)
>>> hf jobs run --timeout 2h pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel python train.py
>>> hf jobs run --timeout 90m python:3.12 python process_data.py
>>> hf jobs run --timeout 1.5h python:3.12 python train.py # floats are supported--timeout 選項也適用於 UV 指令碼和計劃作業
# UV script with timeout
>>> hf jobs uv run --timeout 2h training_script.py
# Scheduled job with timeout
>>> hf jobs scheduled run @daily --timeout 4h python:3.12 python daily_task.py如果您的作業超過了超時時間，它將被自動終止。始終為長時間執行的任務設定適當的超時時間，並留有緩衝，以避免意外的作業終止。
硬體
可用的 --flavor 選項
- CPU：
cpu-basic,cpu-upgrade - GPU：
t4-small,t4-medium,l4x1,l4x4,a10g-small,a10g-large,a10g-largex2,a10g-largex4,a100-large - TPU：
v5e-1x1,v5e-2x2,v5e-2x4
(於 2025 年 07 月更新自 Hugging Face suggested_hardware 文件)
標籤
使用 -l 或 --label 為作業新增標籤。標籤是鍵值對，用於為作業應用元資料。要為一個作業應用兩個標籤，請重複標籤標誌（-l 或 --label）
>>> hf jobs run -l my-label --label foo=bar ubuntu echo "This Job has multiple labels"鍵 my-label 沒有指定值，因此其值預設為空字串 ("")。
在 hf jobs ps 中使用 -f 或 --filter 來過濾與特定標籤匹配的作業
# Show fine-tuning Jobs
>>> hf jobs ps -a --filter label=fine-tuning
# Show Jobs that don't have the "prod" label and have a label that starts with "data-"
>>> hf jobs ps -a --filter label!=prod --filter "label=data-*"
# Show Jobs based on key=value labels
>>> hf jobs ps -a --filter label=model=Qwen3-06B --filter label=dataset!=CapybaraUV 指令碼（實驗性）
在 HF 基礎設施上執行 UV 指令碼（帶有內聯依賴項的 Python 指令碼）。UV 指令碼是 Python 指令碼，它們透過特殊的註釋語法直接在檔案中包含其依賴項。
# Run a UV script (creates temporary repo)
>>> hf jobs uv run my_script.py
# Run with persistent repo
>>> hf jobs uv run my_script.py --repo my-uv-scripts
# Run with GPU
>>> hf jobs uv run ml_training.py --flavor gpu-t4-small
# Pass arguments to script
>>> hf jobs uv run process.py input.csv output.parquet
# Add dependencies
>>> hf jobs uv run --with transformers --with torch train.py
# Run a script directly from a URL
>>> hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.py
# Run a command
>>> hf jobs uv run --with lighteval python -c 'import lighteval'UV 指令碼是 Python 指令碼，它們透過特殊的註釋語法直接在檔案中包含其依賴項。這使它們非常適合不需要複雜專案設定的獨立任務。在 UV 文件中瞭解有關 UV 指令碼的更多資訊。
可以使用 -- 來分隔命令和作業/UV 選項，以提高畫質晰度，例如 hf jobs uv run --flavor gpu-t4-small --with torch -- python -c '...'
hf jobs scheduled
排程和管理將在 HF 基礎設施上執行的任務。
排程應為以下之一：@annually, @yearly, @monthly, @weekly, @daily, @hourly，或 CRON 排程表示式（例如，"0 9 * * 1" 表示每週一早上 9 點）。
# Schedule a job that runs every hour
>>> hf jobs scheduled run @hourly python:3.12 python -c 'print("This runs every hour!")'
# Use the CRON syntax
>>> hf jobs scheduled run "*/5 * * * *" python:3.12 python -c 'print("This runs every 5 minutes!")'
# Schedule with GPU
>>> hf jobs scheduled run @hourly --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c "import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")"
# Schedule a UV script
>>> hf jobs scheduled uv run @hourly my_script.py使用與 hf jobs run 相同的引數來傳遞環境變數、secrets、timeout 等。
使用以下命令管理計劃中的作業：
# List your active scheduled jobs
>>> hf jobs scheduled ps
# Inspect the status of a job
>>> hf jobs scheduled inspect <scheduled_job_id>
# Suspend (pause) a scheduled job
>>> hf jobs scheduled suspend <scheduled_job_id>
# Resume a scheduled job
>>> hf jobs scheduled resume <scheduled_job_id>
# Delete a scheduled job
>>> hf jobs scheduled delete <scheduled_job_id>hf endpoints
使用 hf endpoints 直接從終端管理 Inference Endpoints：列出、部署、描述和管理。為了相容性，仍然保留了舊的 hf inference-endpoints 別名。
# Lists endpoints in your namespace
>>> hf endpoints ls
# Deploy an endpoint from Model Catalog
>>> hf endpoints catalog deploy --repo openai/gpt-oss-120b --name my-endpoint
# Deploy an endpoint from the Hugging Face Hub
>>> hf endpoints deploy my-endpoint --repo gpt2 --framework pytorch --accelerator cpu --instance-size x2 --instance-type intel-icl
# List catalog entries
>>> hf endpoints catalog ls
# Show status and metadata
>>> hf endpoints describe my-endpoint
# Pause the endpoint
>>> hf endpoints pause my-endpoint
# Delete without confirmation prompt
>>> hf endpoints delete my-endpoint --yes新增
--namespace來指定組織，新增--token來覆蓋身份驗證。
hf endpoints catalog
使用 hf endpoints catalog 與 Inference Endpoints 模型目錄進行互動。可以直接從目錄中部署具有最佳化配置的模型。
# List available catalog models
>>> hf endpoints catalog ls
# Deploy a model from the catalog
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct
# Deploy with a custom name
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct --name my-llama-endpoint