インストール

開始する前に、適切なパッケージをインストールして環境を設定する必要があります。

huggingface_hubはPython 3.10+でテストされています。

pipでインストール

huggingface_hubのインストールは、仮想環境で行うことを強く推奨します。 Pythonの仮想環境に慣れていない場合は、このガイドをご覧ください。 仮想環境を使用すると、異なるプロジェクトの管理が容易になり、依存関係間の互換性問題を回避できます。

プロジェクトディレクトリで仮想環境を作成することから始めます:

python -m venv .venv

仮想環境を有効化します。LinuxおよびmacOSの場合:

source .venv/bin/activate

Windowsで仮想環境を有効にするには:

.venv/Scripts/activate

これで、huggingface_hub を PyPi レジストリから インストールする準備が整いました:

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バージョンの動作を維持するよう努めており、ほとんどの問題は通常、数時間から1日以内に解決されます。問題が発生した場合は、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をインストールする

Python環境を変更せずにhf CLIを設定するには、ワンライナーインストーラーを使用してください:

macOSおよびLinuxでは:

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

Windowsの場合:

powershell -ExecutionPolicy ByPass -c "irm https://hf.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'))"

このコマンドは、gpt2 モデルに関する情報を Hub から取得します。 出力は次のようになるはずです:

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が正しくインストールされたら、環境変数を設定するか、ガイドのいずれかを確認して始めることをお勧めします。