安裝

在開始之前，您需要透過安裝相應的包來設定您的環境。

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

使用 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 both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'

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

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

從原始碼安裝

在某些情況下，從原始碼直接安裝 huggingface_hub 是很有趣的。這允許您使用最新的 main 版本，而不是最新的穩定版本。main 版本有助於及時瞭解最新發展，例如，如果自上次官方釋出以來已修復了一個錯誤，但新版本尚未推出。

但是，這意味著 main 版本可能並不總是穩定的。我們努力保持 main 版本執行正常，並且大多數問題通常在幾個小時或一天內得到解決。如果您遇到問題，請開啟一個 Issue，以便我們能更快地解決它！

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

從原始碼安裝時，您還可以指定特定分支。如果您想測試一個尚未合併的新功能或新 bug 修復，這很有用

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/。

安裝 Hugging Face CLI

使用我們的一行安裝程式，在不接觸 Python 環境的情況下設定 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"

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

後續步驟

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