安裝

在開始之前，您需要透過安裝適當的軟體包來設定您的環境。

huggingface_hub 在 Python 3.8+ 上進行了測試。

使用 pip 安裝

強烈建議在虛擬環境中安裝 huggingface_hub。如果您不熟悉 Python 虛擬環境，請檢視此指南。虛擬環境使管理不同的專案變得更容易，並避免依賴項之間的相容性問題。

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

python -m venv .env

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

source .env/bin/activate

在 Windows 上啟用虛擬環境

.env/Scripts/activate

現在您已準備好從 PyPi 登錄檔安裝 huggingface_hub

pip install --upgrade huggingface_hub

完成後，檢查安裝是否正常工作。

安裝可選依賴項

huggingface_hub 的某些依賴項是可選的，因為它們不是執行 huggingface_hub 核心功能所必需的。但是，如果未安裝可選依賴項，huggingface_hub 的某些功能可能不可用。

您可以透過 pip 安裝可選依賴項

# Install dependencies for tensorflow-specific features
# /!\ Warning: this is not equivalent to `pip install tensorflow`
pip install 'huggingface_hub[tensorflow]'

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

以下是 huggingface_hub 中的可選依賴項列表

• cli: 為 huggingface_hub 提供更方便的 CLI 介面。
• fastai, torch, tensorflow: 執行框架特定功能的依賴項。
• dev: 貢獻於庫的依賴項。包括 testing（執行測試）、typing（執行型別檢查器）和 quality（執行 linter）。

從原始碼安裝

在某些情況下，直接從原始碼安裝 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

完成後，檢查安裝是否正常工作。

可編輯安裝

從原始碼安裝允許您設定可編輯安裝。如果您計劃為 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/。

使用 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 限制

為了實現機器學習普惠化的目標，我們構建了 huggingface_hub，使其成為一個跨平臺庫，尤其是在基於 Unix 和 Windows 系統上都能正常工作。但是，在 Windows 上執行 huggingface_hub 時，在少數情況下存在一些限制。以下是已知問題的詳盡列表。如果您遇到任何未記錄的問題，請透過在 Github 上提交 Issue 告知我們。

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

後續步驟

在您的機器上正確安裝 huggingface_hub 後，您可能需要配置環境變數或檢視我們的指南之一以開始使用。