ストレージバケット

Storage Buckets は、Hugging Face Hub におけるリポジトリの一種で、Xet ストレージバックエンドによって提供される S3 類似のオブジェクトストレージです。Git ベースのリポジトリ（モデル、データセット、Spaces）とは異なり、バケットはバージョン管理なしかつ変更可能であり、トレーニングチェックポイント、ログ、中間成果物、またはバージョン管理を必要としない大規模なファイル群など、シンプルで高速なストレージが必要なユースケース向けに設計されています。

バケットには、HubのWebインターフェース、hf CLI、またはPython APIを使用して操作できます。

Bucketsはすべてのユーザーと組織で利用できます。料金詳細については、hf.co/storageを参照してください。

ツールからバケットデータにアクセスする方法（ファイルシステムとしてマウント、hf:// パス、Jobs/Spaces でのボリュームマウント）については Access Patterns を、既存の S3 ツール（AWS CLI、boto3、s5cmd）を使用するには S3-Compatible API を、pandas、Dask、Spark などの人気データライブラリでそのまま使えるスニペットについては Bucket Integrations を参照してください。

バケットとリポジトリ

Hubには2種類のストレージが用意されています。バージョン管理と共同作業向けのGitベースのリポジトリ、および高速で変更可能なオブジェクトストレージ向けのバケットです。

バージョン履歴、コラボレーション機能（PR、ディスカッション）、ライブラリ統合を必要とする場合は、リポジトリを使用してください。頻繁に変更されるデータの高速な変更可能ストレージを必要とする場合は、バケットを使用してください。ファイルはインプレースで上書きまたは削除できます。

バケットの作成

Hub UIから

1. huggingface.co/new-bucket に移動します:

2. バケットの所有者を指定します。これは、あなた自身または所属している組織のいずれかです。

3. バケット名を入力してください。

4. バケットを公開にするか非公開にするかを選択します。

5. 必要に応じて、CDNプリウォーミングのリージョンを事前選択し、データを開始時点で計算リソースの近くにキャッシュできます。

バケットを作成した後、バケットのページが表示されるはずです:

CLIから

# Create a bucket under your namespace
hf buckets create my-bucket

# Create a private bucket
hf buckets create my-bucket --private

# Create a bucket under an organization
hf buckets create my-org/shared-bucket

Pythonから

from huggingface_hub import create_bucket

# Create a bucket under your namespace
create_bucket("my-bucket")

# Create a private bucket
create_bucket("my-bucket", private=True)

# Create a bucket under an organization
create_bucket("my-org/shared-bucket")

可視性の変更

バケットの作成後、その可視性を変更できます:

# Make a bucket private
hf buckets settings username/my-bucket --private

# Make it public again
hf buckets settings username/my-bucket --public

from huggingface_hub import update_bucket_settings

update_bucket_settings("username/my-bucket", private=True)
update_bucket_settings("username/my-bucket", private=False)

バケットの削除、移動、一覧表示を含む完全なPython APIリファレンスについては、huggingface_hubのBucketsガイドを参照してください。

Hubでのバケットの閲覧

各バケットには、Hub上にページがあり、その中身を確認し、ディレクトリを移動し、ファイルの詳細を表示できます。バケットページはhttps://huggingface.co/buckets/<owner>/<bucket-name>で利用できます。

READMEのレンダリング

バケット内のディレクトリにREADME.mdファイルが含まれている場合、Hubはそのディレクトリのページでファイル一覧の下にレンダリングします。これはバケットのルートディレクトリでも、任意のサブディレクトリ内でも機能します。バケットの内容、データの構成方法、または下流のツールがどのようにデータを消費すべきかを文書化するために便利です。

CLIからの一覧表示

CLIからバケットの内容をリスト表示することもできます:

# List files in a bucket (with human-readable sizes)
hf buckets list julien-c/my-training-bucket -h
                     Feb 17 14:46  art/
                     Feb 17 14:58  arxivqa/
                     Feb 17 15:02  arxivqa2/
                     Feb 17 15:04  arxivqa3/
                     Feb 17 14:47  captcha/
                     Feb 17 14:53  captcha2/
                     Feb 24 17:22  julien/

# Recursive listing
hf buckets list julien-c/my-training-bucket/art -h -R
    423.6 MB         Feb 17 14:29  art/train-00000-of-00011.parquet
    441.0 MB         Feb 17 14:29  art/train-00001-of-00011.parquet
    521.7 MB         Feb 17 14:29  art/train-00002-of-00011.parquet
    481.4 MB         Feb 17 14:29  art/train-00003-of-00011.parquet
    444.6 MB         Feb 17 14:29  art/train-00004-of-00011.parquet
    461.6 MB         Feb 17 14:29  art/train-00005-of-00011.parquet
    466.4 MB         Feb 17 14:29  art/train-00006-of-00011.parquet
    486.3 MB         Feb 17 14:29  art/train-00007-of-00011.parquet
    477.0 MB         Feb 17 14:29  art/train-00008-of-00011.parquet
    454.0 MB         Feb 17 14:29  art/train-00009-of-00011.parquet
    483.1 MB         Feb 17 14:29  art/train-00010-of-00011.parquet

# Tree view
hf buckets list julien-c/my-training-bucket --tree -h -R
                        ├── art/
423.6 MB  Feb 17 14:29  │   ├── train-00000-of-00011.parquet
441.0 MB  Feb 17 14:29  │   ├── train-00001-of-00011.parquet
521.7 MB  Feb 17 14:29  │   ├── train-00002-of-00011.parquet
481.4 MB  Feb 17 14:29  │   ├── train-00003-of-00011.parquet
444.6 MB  Feb 17 14:29  │   ├── train-00004-of-00011.parquet
461.6 MB  Feb 17 14:29  │   ├── train-00005-of-00011.parquet
466.4 MB  Feb 17 14:29  │   ├── train-00006-of-00011.parquet
486.3 MB  Feb 17 14:29  │   ├── train-00007-of-00011.parquet
477.0 MB  Feb 17 14:29  │   ├── train-00008-of-00011.parquet
454.0 MB  Feb 17 14:29  │   ├── train-00009-of-00011.parquet
483.1 MB  Feb 17 14:29  │   └── train-00010-of-00011.parquet
                        ├── arxivqa/
495.9 MB  Feb 17 14:32  │   ├── train-00000-of-00164.parquet
518.3 MB  Feb 17 14:32  │   ├── train-00001-of-00164.parquet
495.5 MB  Feb 17 14:32  │   ├── train-00002-of-00164.parquet
486.6 MB  Feb 17 14:32  │   ├── train-00003-of-00164.parquet
490.4 MB  Feb 17 14:32  │   ├── train-00004-of-00164.parquet
...

ファイルの管理

Hubのバケットページからファイルを直接アップロードおよびダウンロードできます。また、CLIやPython APIを使用してプログラム的にアクセスすることもできます。バケット内のファイルはhf://buckets/パス（例: hf://buckets/username/my-bucket/path/to/file）で参照されます。hf buckets cpコマンドは個別のファイル転送に対応し、hf buckets syncはディレクトリに適しています。すべてのコマンドは、ローカルからリモートへ、およびリモートからローカルへの両方向で動作します。

データがすでにモデル、データセット、または Space リポジトリ（または他のバケット）に存在する場合、hf buckets cp を使用してサーバーサイドでコピーできます。ダウンロードや再アップロードは不要です。リポジトリとバケット間のファイルコピーを参照してください。

ファイルのアップロード

クイックなアップロードには、ブラウザのバケットページにファイルを直接ドラッグ＆ドロップできます。プログラムでの使用には、hf buckets cp を使用して個別のファイルをバケットにコピーします。ソースはローカルパス、デスティネーションは hf://buckets/ パスです。また、stdin からデータをパイプすることもでき、プログラムで生成されたコンテンツに対して便利です。

CLI:

# Upload a single file
hf buckets cp ./model.safetensors hf://buckets/username/my-bucket/models/model.safetensors

# Upload from stdin
cat config.json | hf buckets cp - hf://buckets/username/my-bucket/config.json

Pythonでは、batch_bucket_filesを使用して、1回の呼び出しで1つ以上のファイルをアップロードできます。各エントリは(local_path, remote_path)のタプルです。

Python:

from huggingface_hub import batch_bucket_files

batch_bucket_files(
    "username/my-bucket",
    add=[
        ("./model.safetensors", "models/model.safetensors"),
        ("./config.json", "models/config.json"),
    ],
)

その他のアップロードオプション（生バイト、アップロードと削除の組み合わせなど）については、huggingface_hub アップロードガイドを参照してください。

ファイルのダウンロード

Hubのバケットページでファイルを直接クリックすることで、個別のファイルをダウンロードできます。プログラムによるアクセスでは、ダウンロードはアップロードの構文を反映しており、hf buckets cpのソースとデスティネーションを入れ替えます。また、デスティネーションに-を指定することで、ファイルをstdoutにストリーミングし、バケットの内容を他のツールに直接パイプできます。

CLI:

# Download a single file
hf buckets cp hf://buckets/username/my-bucket/models/model.safetensors ./model.safetensors

# Download to stdout and pipe
hf buckets cp hf://buckets/username/my-bucket/config.json - | jq .

Pythonでは、(remote_path, local_path)のタプルのリストを引数にdownload_bucket_filesを使用します。

Python:

from huggingface_hub import download_bucket_files

download_bucket_files(
    "username/my-bucket",
    files=[
        ("models/model.safetensors", "./local/model.safetensors"),
        ("config.json", "./local/config.json"),
    ],
)

事前取得したメタデータを用いた高速なダウンロードについては、huggingface_hub のダウンロードガイドを参照してください。

ディレクトリの同期

sync コマンドは rsync や aws s3 sync と同様に動作し、ソースとデスティネーションを比較して、変更されたファイルのみを転送します。これは、ローカルディレクトリとバケットを同期させる最も効率的な方法です。デフォルトでは、sync はファイルの追加と更新のみを行います。ソースに存在しなくなったデスティネーションのファイルも削除するには、--delete を指定してください。何も転送せずに何が起きるかをプレビューするには、--dry-run を使用してください。

CLI:

# Upload a local directory to a bucket
hf buckets sync ./data hf://buckets/username/my-bucket/data

# Download from a bucket to a local directory
hf buckets sync hf://buckets/username/my-bucket/data ./data

# Sync with deletion of extraneous files
hf buckets sync ./data hf://buckets/username/my-bucket/data --delete

# Preview what would be synced without executing
hf buckets sync ./data hf://buckets/username/my-bucket/data --dry-run

# Plan and apply: review the sync plan before executing
hf buckets sync ./data hf://buckets/username/my-bucket/data --plan sync-plan.jsonl
# ... review the plan file, then apply it
hf buckets sync --apply sync-plan.jsonl

hf sync は hf buckets sync の便利なエイリアスです。

Python:

from huggingface_hub import sync_bucket

# Upload a local directory to a bucket
sync_bucket("./data", "hf://buckets/username/my-bucket/data")

# Download from a bucket to a local directory
sync_bucket("hf://buckets/username/my-bucket/data", "./data")

sync コマンドは、フィルタリング（--include、--exclude）、比較モード（--ignore-times、--existing）、および実行前に操作を確認するためのplan-and-applyワークフローをサポートしています。すべてのオプションについては、huggingface_hub sync ガイドを参照してください。

ファイルの削除

バケットは非バージョン管理であるため、削除は即座かつ恒久的に行われます。一度削除されたファイルを復元する方法はありません。ファイルを削除する前に、特に--recursiveを使用する場合は、--dry-runを使って内容を確認してください。

CLI:

# Remove a single file
hf buckets rm username/my-bucket/old-model.bin

# Remove all files under a prefix
hf buckets rm username/my-bucket/logs/ --recursive

# Preview what would be deleted
hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-run

Python:

from huggingface_hub import batch_bucket_files

batch_bucket_files("username/my-bucket", delete=["old-model.bin", "logs/debug.log"])

その他の削除オプション（パターンベースのフィルタリング、再帰的な削除など）については、huggingface_hub の削除ガイドを参照してください。

リポジトリとバケット間のファイルのコピー

Xetで管理されているファイルは、リポジトリ（モデル、データセット、Space）やバケットから、データのリアップロードなしで別のバケットにコピーできます。コピーはサーバーサイドで実行されるため、移行されるのはXetのコンテンツハッシュのみです。これにより、チャンクレベルの重複排除のおかげで、非常に大きなファイルであっても瞬時にコピーできます。

Xetで管理されているファイルのみがサーバー間でコピーされます。小さい非Xetファイル（設定ファイルやREADMEなど）は、自動的にダウンロードされて再アップロードされます。サーバーサイドのコピーには、ソースと宛先が同じストレージリージョンにある必要があります。

CLI:

hf buckets cp \
  hf://datasets/HuggingFaceFW/fineweb/data \
  hf://buckets/username/fineweb-data

Python:

from huggingface_hub import HfApi

api = HfApi()

api.copy_files(
    "hf://datasets/HuggingFaceFW/fineweb/data",
    "hf://buckets/username/fineweb-data",
)

ソースのリポジトリまたはバケットへの読み取りアクセス権と、宛先のバケットへの書き込みアクセス権が必要です。

バケットからリポジトリ（モデル、データセット、Space）へ再アップロードなしでデータを転送する機能は現在利用できませんが、ロードマップに含まれています。

変更の追跡

Buckets は可変であるため、バケットのビューを保持するツール（マウント、ファイルシステムレイヤー、同期デーモン、ダッシュボードなど）は、ファイルが変更されたタイミングを把握する必要があります。利用可能なメカニズムは2つあります：

• Webhooks: 管理するサーバーへの HTTP コールバック、または各変更時に開始される Job — Jobs を使用してバケット内の新しいファイルを処理するを参照してください。
• ライブフォロー: クライアントが購読するサーバー送信イベントのストリームです。

ライブフォロー

GET https://huggingface.co/api/buckets/<owner>/<bucket-name>/events は、バケットのファイル変更をserver-sent eventsとしてストリーミングします。リクエストにはAccept: text/event-streamを指定する必要があります（指定しないと400が返されます）。また、バケットのリスト表示と同じ読み取りアクセス権限が必要です。パブリックなバケットの場合はトークンは不要です。パラメータとレスポンススキーマの詳細については、OpenAPI specを参照してください。

curl -N -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/buckets/username/my-bucket/events"

Pythonでは、ストリームを自分で消費する必要はありません。HfFileSystemはlive_follow=Trueを指定することでこれを追跡し、別のプロセスがバケットを変更した場合でも、キャッシュされたリストが最新の状態に保たれます。

コピーしました

from huggingface_hub import HfFileSystem

hffs = HfFileSystem(live_follow=True)
hffs.ls("buckets/username/my-bucket/data")  # starts following the bucket

fsspecのstorage_optionsを受け取るライブラリ（pandas、PyArrowなど）も、これを受け入れます。

ストリームは4つのイベントタイプを出力します:

changes の各エントリには、path と op（add、update、または delete）が含まれます。add または update の場合、変更されたフィールド（size、xetHash、uploadedAt、mtime、mtimeNanos）も含まれます。そのため、ファイルが同一の内容で再アップロードされた場合、update は新しい uploadedAt のみを含む非常に小さなものになる可能性があります。変更されなかったフィールドは省略されます。また、アップロードによって mtime/mtimeNanos がクリアされた場合、これらは null になるため、欠落と null は同様に扱う必要があります。

event: ready
data: {"cursor":"..."}

event: changes
data: {"cursor":"...","changes":[{"path":"data/train.txt","op":"add","size":20,"uploadedAt":"2026-09-16T09:21:45.000Z"},{"path":"data/old.txt","op":"delete"}]}

再開。接続した時点で新しいストリームが開始されます。見逃した変更も取得するには、最後に受信したcursor（すべてのreadyおよびchangesイベントに付随します）を?cursor=<cursor>として渡すか、タイムスタンプを?since=<ISO timestamp>として渡します（開始時刻を含む。例: 2026-09-16T09:21:45Z）。

変更の直近約15分間のみがリプレイ可能です。cursorまたはsinceがそれより古い場合、リプレイの代わりにresetを受信します。その場合は、バケットを一度列挙してビューを再構築し、その後、新しいストリームのreadyイベントのcursorから再度フォローしてください。再開は、接続の切断や再起動のような短いギャップを埋めることを目的としています。より長い間隔で離れていたクライアントは、再列挙を行うことを想定してください。

再接続中。 長時間維持される接続はリサイクルされます。約20分ごと（およびデプロイ中）にサーバーがreconnectを送信し、その後ストリームを終了します。いかなるストリームの終了も同様に扱ってください。最後に受信したカーソルで再接続します。接続を維持するために30秒ごとに: pingコメントが送信されるため、完全に沈黙したストリームは切断されたものとみなせます。

503レスポンスは、ライブフォローが一時的に利用できないことを示します。Retry-Afterヘッダーに記載された遅延時間後に再試行してください。

プレウォーミングとCDN

バケットはデフォルトで、Hubのグローバルストレージ上に配置されます。ストレージの場所がスループットに直接影響を与えるワークロードでは、プリウォームによってバケットのデータをコンピューティングリソースの近くに移動させることができます。

Pre-warmingは、特定のクラウドプロバイダーやリージョンに近いエッジロケーションにファイルをキャッシュします。これにより、ジョブはデータをリモートリージョンから取得するのではなく、ローカルで読み取ることができます。これは特に次の場合に役立ちます:

• 大規模なデータセットやチェックポイントへの高速アクセスが必要なトレーニングクラスター
• パイプラインの異なる部分が異なるクラウドで実行されるマルチリージョン構成
• 世界中の多くのユーザーに大規模な成果物を配布する

利用可能なリージョンとプレウォーミングの有効化の詳細については、hf.co/storageを参照してください。

ユースケース

トレーニングのチェックポイントとログ

トレーニングジョブ（Jobs経由など）を実行する際は、チェックポイントとログをバケットに保存してください。Gitリポジトリとは異なり、バージョン履歴が蓄積されることなく最新のチェックポイントを上書きでき、syncにより変更されたデータのみが転送されることを保証します。

# After each evaluation step, sync checkpoints to a bucket
hf sync ./checkpoints hf://buckets/my-org/training-run-42/checkpoints

バケットはXetを基盤としているため、モデルの大部分が固定された連続するチェックポイントでは、チャンクレベルの重複排除の恩恵を受けることができます。変更されたチャンクのみがアップロードされます。

データ処理パイプライン

バケットは、データ処理ワークフローのステージングエリアとして機能します。生データを処理し、中間出力をバケットに書き出し、パイプラインが完了したら最終成果物をバージョン管理されたDatasetリポジトリに昇格させます。これにより、バージョン管理されたリポジトリをクリーンな状態に保ちつつ、パイプラインには高速な変更可能なストレージを提供します。

Bucketからリポジトリへ再アップロードせずにデータを転送する機能は現在利用できませんが、ロードマップに含まれています。

エージェント型ストレージ

AIエージェントは、中間結果、ツールの出力、トレース、ワーキングメモリなどのための一時ストレージを必要とします。バケットは、このデータのためのHubネイティブな保存場所を提供します。Gitのオーバーヘッドなしで高速な変更可能なアクセスが可能であり、標準的なHugging Faceの権限管理が適用され、Hubエコシステム全体でhf://buckets/パスによってアドレス指定できます。

ローリングバックアップ

バケットはローリングバックアップの維持に適しています。GitベースのDatasetリポジトリでは、古いファイルを削除してもストレージは解放されません。Gitの履歴はすべての過去のバージョンを保持するため、実際にスペースを回収するにはコミットをsquashするか履歴を書き換える必要があります。一方、バケットでは、古いファイルは削除された時点で完全に消去され、現在保存されているもののみに対して課金されます。

# Sync today's backup, removing files that no longer exist locally
hf sync ./daily-backup hf://buckets/my-user/backups/latest --delete

バケットへのモデルのリンク

モデルカードのメタデータにbucketsフィールドを追加することで、モデルとバケットの間に双方向のリンクを作成できます。リンクされたモデルはバケットページに表示され、バケットはモデルページのタグとして表示されます。

# In the model card YAML frontmatter
buckets:
- my-org/my-bucket

詳細については、モデルカードのドキュメントにあるバケットの指定を参照してください。

料金

Storage Bucketsは、保存されたデータ量に基づいて課金され、TBあたりのシンプルな料金体系が適用されます。Enterpriseプランでは、重複排除ベースの課金が適用され、ファイル間で共有されるチャンクが直接課金対象の容量を削減します。

その他のリポジトリについては、バケットの作成は無料であり、無料のストレージ枠が用意されています。無料枠を超える利用については、hf.co/storageを参照してください。一般的な請求に関する情報については、Billingドキュメントを参照してください。