クイックスタート

Hugging Face Hubは、機械学習モデル、デモ、データセット、メトリクスの共有のための主要なプラットフォームです。huggingface_hubライブラリを使用すると、開発環境から離れることなくHubとやり取りできます。リポジトリの作成と管理、ファイルのダウンロードとアップロード、Hubからのモデルやデータセットのメタデータ取得を簡単に実行できます。

インストール

始めるには、huggingface_hubライブラリをインストールしてください:

pip install --upgrade huggingface_hub

詳細については、インストールガイドをご覧ください。

huggingface_hubには、ターミナルから直接Hubと対話できるhf CLIも同梱されています。 AIエージェント（Claude Code、Codex、Cursorなど）を使用している場合は、Skillをインストールして、エージェントがCLIを使用できるようにしてください。

コピーしました

# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add

詳細については、AIエージェント向けHugging Face CLIガイドをご覧ください。

ファイルのダウンロード

Hub上のリポジトリはgitでバージョン管理されており、ユーザーは単一のファイルまたはリポジトリ全体をダウンロードできます。hf_hub_download()関数を使用してファイルをダウンロードできます。この関数は、ファイルをローカルディスクにダウンロードしてキャッシュします。次にそのファイルが必要になった場合、キャッシュから読み込まれるため、再ダウンロードする必要はありません。

ダウンロードしたいファイルのリポジトリIDとファイル名が必要です。例えば、Pegasusモデルの設定ファイルをダウンロードするには:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")

特定のバージョンのファイルをダウンロードするには、revision パラメータを使用して、ブランチ名、タグ、またはコミットハッシュを指定します。コミットハッシュを使用する場合は、短い7文字のコミットハッシュではなく、フルレングスのハッシュを指定する必要があります:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
...     repo_id="google/pegasus-xsum",
...     filename="config.json",
...     revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )

詳細とオプションについては、hf_hub_download()のAPIリファレンスを参照してください。

認証

多くの場合、Hubで操作を行うにはHugging Faceアカウントでの認証が必要です。プライベートリポジトリのダウンロード、ファイルのアップロード、PRの作成などです。アカウントをお持ちでない場合は、アカウントを作成してください。

ログインコマンド

認証を行う最も簡単な方法は、login()コマンドを使用することです:

hf auth login

すでにログインしている場合、コマンドは即座に返ります。再ログインを強制するには、hf auth login --force を使用します。ログインしていない場合、ブラウザでのログインを促されます。表示された URL を開き、短いコードを入力してリクエストを承認すると、アクセストークンが取得され、HF_HOME ディレクトリ（デフォルトは ~/.cache/huggingface/token）に保存されます。トークンは一定期間後に期限切れになりますが、使用を継続している限り自動的に更新されます。Hub とやり取りするスクリプトやライブラリは、リクエストを送信する際にこのトークンを使用します。代わりに、Settings page で生成した User Access Token を貼り付けることもできます。

User Access Tokens には read または write の権限があります。リポジトリの作成や編集を行う場合は、write アクセス権限を持つトークンを使用してください。それ以外の場合は、トークンが意図せず漏洩した場合のリスクを低減するため、read トークンを生成するのが望ましいです。

代わりに、ノートブックやスクリプト内でlogin()を使用してプログラム的にログインすることもできます。

>>> from huggingface_hub import login
>>> login()

同時にログインできるのは1つのアカウントのみです。新しいアカウントにログインすると、自動的に以前のアカウントからログアウトされます。現在アクティブなアカウントを確認するには、hf auth whoamiコマンドを実行してください。

ログイン後、Hub へのすべてのリクエスト - 認証が必ずしも必要ではないメソッドを含む - は、デフォルトでアクセストークンを使用します。トークンの暗黙的な使用を無効にする場合は、環境変数として HF_HUB_DISABLE_IMPLICIT_TOKEN=1 を設定してください（リファレンスを参照）。

ローカルで複数のトークンを管理する

各トークンでlogin()コマンドにログインするだけで、マシンに複数のトークンを保存できます。ローカルでこれらのトークンを切り替える必要がある場合は、auth switchコマンドを使用できます。

hf auth switch

このコマンドを実行すると、保存されたトークンのリストから名前を指定してトークンを選択するよう促されます。選択すると、選択したトークンがアクティブなトークンとなり、Hubとのすべてのやり取りで使用されます。

hf auth list を使用して、マシン上で利用可能なすべてのアクセストークンを一覧表示できます。

環境変数

環境変数HF_TOKENも認証に使用できます。これは、HF_TOKENをSpace secretとして設定できるSpaceで特に便利です。

新機能: Google Colaboratoryでは、ノートブック用の秘密鍵を定義できます。HF_TOKENのシークレットを定義すると、自動的に認証されます!

環境変数またはシークレットによる認証は、マシンに保存されたトークンよりも優先されます。

メソッドのパラメータ

最後に、tokenをパラメータとして受け取る任意のメソッドにトークンを渡すことで認証することも可能です。

from huggingface_hub import whoami

user = whoami(token=...)

トークンを永続的に保存したくない場合、または複数のトークンを同時に処理する必要がある場合を除き、通常は推奨されません。

トークンをパラメータとして渡す際は注意してください。トークンをコードベースやノートブックにハードコードするのではなく、安全なボルトから読み込むことが常にベストプラクティスです。コードを誤って共有した場合、ハードコードされたトークンは重大な漏洩リスクを伴います。

リポジトリを作成する

登録とログインが完了したら、create_repo()関数を使用してリポジトリを作成します:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")

リポジトリをプライベートにしたい場合は、次のようにしてください。

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)

プライベートリポジトリは、あなた自身以外には表示されません。

リポジトリを作成するか、Hub にコンテンツをプッシュするには、write 権限を持つ User Access Token を提供する必要があります。権限は、Settings page でトークンを作成する際に選択できます。

ファイルのアップロード

upload_file()関数を使用して、新しく作成したリポジトリにファイルを追加します。以下を指定する必要があります:

1. アップロードするファイルのパス。
2. リポジトリ内のファイルのパス。
3. ファイルを追加したいリポジトリのID。

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/home/lysandre/dummy-test/README.md",
...     path_in_repo="README.md",
...     repo_id="lysandre/test-model",
... )

一度に複数のファイルをアップロードするには、Uploadガイドを参照してください。このガイドでは、ファイルのアップロード方法（gitを使用する場合と使用しない場合）をいくつか紹介します。

次のステップ

huggingface_hub ライブラリは、Python を使って Hub と簡単にやり取りするための方法を提供します。Hub 上でファイルやリポジトリを管理する方法について詳しく知るには、以下の ハウツーガイド の閲覧をお勧めします。

• リポジトリの管理。
• ダウンロードHubからファイルを。
• ファイルをアップロードします。
• Hubを検索して、希望するモデルまたはデータセットを探します。
• Hugging Face Hub にホストされているモデルに対して、複数のサービスで推論を実行します。