安裝

在開始之前，您需要安裝適當的套件來設定您的環境。

huggingface_hub 已在 Python 3.10+ 上進行測試。

使用 pip 安裝

強烈建議在虛擬環境中安裝 huggingface_hub。如果您不熟悉 Python 虛擬環境，請參考此指南。虛擬環境可以讓您更輕鬆地管理不同的專案，並避免相依套件之間的相容性問題。

首先在您的專案目錄中建立一個虛擬環境

python -m venv .venv

啟用虛擬環境。在 Linux 和 macOS 上

source .venv/bin/activate

在 Windows 上啟用虛擬環境

.venv/Scripts/activate

現在您可以準備從 PyPi 註冊表安裝 huggingface_hub 了

pip install --upgrade huggingface_hub

完成後，請檢查安裝是否正確運作。

安裝選擇性相依套件

huggingface_hub 的某些相依套件是選擇性的，因為執行 huggingface_hub 的核心功能並不需要它們。但是，如果沒有安裝這些選擇性套件，huggingface_hub 的某些功能可能無法使用。

您可以透過 pip 安裝選擇性相依套件

# Install dependencies for both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'

以下是 huggingface_hub 中選擇性相依套件的列表

• fastai, torch：用於執行特定框架功能的相依套件。
• dev：用於貢獻程式庫的相依套件。包含 testing（執行測試）、typing（執行型別檢查）以及 quality（執行代碼檢查工具）。

從原始碼安裝

在某些情況下，直接從原始碼安裝 huggingface_hub 是很有用的。這讓您可以使用最新的 main 版本，而非最新的穩定版本。main 版本有助於跟上最新的開發進度，例如如果某個錯誤在上次正式發布後已修復，但尚未進行新的版本發布時。

然而，這意味著 main 版本不一定總是穩定的。我們致力於保持 main 版本的運作正常，大多數問題通常會在幾小時或一天內解決。如果您遇到問題，請開啟一個 Issue，以便我們能更快地修復它！

pip install git+https://github.com/huggingface/huggingface_hub

從原始碼安裝時，您也可以指定特定的分支。如果您想測試尚未合併的新功能或錯誤修復，這非常有用。

pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch

完成後，請檢查安裝是否正確運作。

可編輯安裝

從原始碼安裝允許您進行可編輯安裝 (editable install)。如果您計畫為 huggingface_hub 做出貢獻並需要測試程式碼變更，這是一種較進階的安裝方式。您需要在您的機器上複製一份 huggingface_hub 的本地副本。

# First, clone repo locally
git clone https://github.com/huggingface/huggingface_hub.git

# Then, install with -e flag
cd huggingface_hub
pip install -e .

這些指令會將您複製儲存庫的資料夾與您的 Python 程式庫路徑連結起來。Python 現在除了正常的程式庫路徑外，也會查看您所複製的資料夾。例如，如果您的 Python 套件通常安裝在 ./.venv/lib/python3.13/site-packages/ 中，Python 也會搜尋您複製的 ./huggingface_hub/ 資料夾。

安裝 Hugging Face CLI

使用我們的一行指令安裝程式來設定 hf CLI，而無需更動您的 Python 環境

在 macOS 和 Linux 上

curl -LsSf https://huggingface.co/cli/install.sh | bash

在 Windows 上

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

若要升級現有的安裝，請執行 hf update — 它會自動偵測 hf 的安裝方式（獨立安裝程式、Homebrew 或 pip）並執行對應的指令。

使用 conda 安裝

如果您對此較為熟悉，可以使用 conda-forge 頻道安裝 huggingface_hub

conda install -c conda-forge huggingface_hub

完成後，請檢查安裝是否正確運作。

檢查安裝

安裝完成後，請執行以下指令來確認 huggingface_hub 是否運作正常

python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"

此指令將從 Hub 獲取關於 gpt2 模型資訊。輸出應如下所示

Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation

Windows 的限制

秉持著讓機器學習（ML）在各地普及化的目標，我們建構了 huggingface_hub 作為跨平台程式庫，特別是確保它能在 Unix 及 Windows 系統上正確運作。然而，在 Windows 上執行時，huggingface_hub 仍有少數限制。以下是已知問題的完整列表。如果您遇到任何未記錄的問題，請透過在 Github 上開啟 Issue 告知我們。

• huggingface_hub 的快取系統依賴符號連結（symlinks）來高效地快取從 Hub 下載的檔案。在 Windows 上，您必須啟用開發人員模式或以系統管理員身分執行指令碼，才能啟用符號連結。若未啟用，快取系統仍可運作，但效率會降低。請閱讀快取限制章節以獲取更多詳細資訊。
• Hub 上的檔案路徑可能包含特殊字元（例如 "path/to?/my/file"）。Windows 對特殊字元的限制較多，這導致在 Windows 上無法下載這些檔案。希望這種情況很少見。如果您認為這是一個錯誤，請聯絡儲存庫擁有者，或聯絡我們以尋求解決方案。

後續步驟

一旦在您的機器上正確安裝了 huggingface_hub，您可能希望設定環境變數或查看我們的指南以開始使用。