# バケット

Buckets は、Xet ストレージバックエンドによって提供される Hugging Face 上の S3 類似のオブジェクトストレージです。リポジトリ（git ベースでファイルの履歴を追跡するもの）とは異なり、Buckets は、コンテンツアドレス可能な重複排除を備えた大規模ファイル用に設計されたリモートオブジェクトストレージコンテナです。バージョン管理が不要な、学習チェックポイント、ログ、中間成果物、または大規模なファイルコレクションの保存など、シンプルで高速な変更可能なストレージが必要なユースケース向けに設計されています。

Python API（[HfApi](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi)）またはCLI（`hf buckets`）を使用してバケットを操作できます。本ガイドでは、利用可能なすべての操作について説明します。

> [!TIP]
> すべての CLI コマンドは `hf buckets <command>` の下で利用できます。詳細については `hf buckets --help` を実行してください。

## バケットの作成と管理

### バケットを作成する

[create_bucket()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.create_bucket) を使用してバケットを作成します。バケット名を指定する必要があります。名前空間を指定しない場合、バケットはユーザー名の下に作成されます。

```py
>>> from huggingface_hub import create_bucket

# Create a bucket under your namespace
>>> url = create_bucket("my-bucket")
>>> url.bucket_id
'username/my-bucket'
>>> url.uri.to_uri()
'hf://buckets/username/my-bucket'

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

# Don't error if bucket already exists
>>> create_bucket("my-bucket", exist_ok=True)
BucketUrl(...)

# Create a bucket in a specific region
>>> create_bucket("my-bucket", region="us")
BucketUrl(...)
```

または、CLI経由で:

```bash
>>> hf buckets create my-bucket
✓ Bucket created
  uri: hf://buckets/Wauplin/my-bucket
  url: https://huggingface.co/buckets/Wauplin/my-bucket

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

# Don't error if bucket already exists
>>> hf buckets create my-bucket --exist-ok

# Create a bucket in a specific region
>>> hf buckets create my-bucket --region us
```

組織配下のバケットを作成するには、`namespace/bucket_name`形式の完全な名前空間を指定することもできます。

```py
>>> from huggingface_hub import create_bucket
>>> create_bucket("my-org/shared-bucket")
```

または、CLI経由で:

```bash
>>> hf buckets create my-org/shared-bucket
```

### バケット情報を取得する

[bucket_info()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.bucket_info) を使用すると、バケットのメタデータ（可視性、総サイズ、ファイル数、作成日）を取得できます。

```py
>>> from huggingface_hub import bucket_info
>>> bucket_info("username/my-bucket")
BucketInfo(
  id='username/my-bucket',
  private=False,
  created_at=datetime.datetime(2026, 2, 12, 17, 42, 12,
  tzinfo=datetime.timezone.utc),
  size=8411791508,
  total_files=128
)
```

または、CLI経由で:

```bash
# JSON output
>>> hf buckets info username/my-bucket
{
  "id": "username/my-bucket",
  "private": false,
  ...
}
```

### バケットのリスト表示

[list_buckets()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.list_buckets) を使用して、名前空間内のすべてのバケットをリスト表示できます。デフォルトでは、現在のユーザーの名前空間内のバケットがリスト表示されます。

```py
>>> from huggingface_hub import list_buckets

# List your own buckets
>>> for bucket in list_buckets():
...     print(bucket.id, bucket.size, bucket.total_files)

# List buckets in an organization
>>> for bucket in list_buckets(namespace="huggingface"):
...     print(bucket.id)
```

またはCLI経由で（`hf buckets ls`は`hf buckets list`の省略形です）：

```bash
# Table format (default)
>>> hf buckets list
ID                   PRIVATE      SIZE TOTAL_FILES CREATED_AT
-------------------- ------- --------- ----------- ----------
username/my-bucket                  32           5 2026-02-16
username/checkpoints         117609095         700 2026-02-13
username/logs                321757477        2000 2026-02-13

# Human-readable sizes
>>> hf buckets list -h
ID                   PRIVATE     SIZE TOTAL_FILES CREATED_AT
-------------------- ------- -------- ----------- ----------
username/my-bucket               32 B           5 2026-02-16
username/checkpoints         117.6 MB         700 2026-02-13
username/logs                321.8 MB        2000 2026-02-13

# List buckets in a specific namespace
>>> hf buckets ls huggingface

# Filter buckets by name
>>> hf buckets list --search "checkpoint"
```

`search` を使用して、バケットを名前でも絞り込むことができます:

```py
>>> for bucket in list_buckets(search="checkpoint"):
...     print(bucket.id)
```

`--quiet` と `--format json` オプションを使用すると、出力形式を変更できます。これは、出力を `grep` や `jq` のような別のツールにパイプしたい場合に特に便利です。

```bash
# Quiet mode: prints one bucket ID per line
>>> hf buckets list --quiet
username/my-bucket
username/checkpoints
username/logs

# JSON format
>>> hf buckets list --format json
[
  {
    "id": "username/my-bucket",
    "private": false,
    "created_at": "2026-02-16T15:28:32+00:00",
    "size": 32,
    "total_files": 5
  },
  ...
]
```

### バケットの可視性を変更

[update_bucket_settings()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.update_bucket_settings) を使用して、既存のバケットをプライベートとパブリックの間で切り替えます。

```py
>>> from huggingface_hub import update_bucket_settings

# Make a bucket private
>>> update_bucket_settings("username/my-bucket", private=True)

# Make it public again
>>> update_bucket_settings("username/my-bucket", private=False)
```

または、CLI経由で:

```bash
# Make a bucket private
>>> hf buckets settings username/my-bucket --private
✓ Bucket settings updated
  bucket_id: username/my-bucket
  private: True

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

### バケットの削除

[delete_bucket()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.delete_bucket) を使用してバケットを削除します。この操作は元に戻せません。

```py
>>> from huggingface_hub import delete_bucket
>>> delete_bucket("username/my-bucket")

# Don't error if bucket doesn't exist
>>> delete_bucket("username/my-bucket", missing_ok=True)
```

または、CLI経由で:

```bash
# Prompts for confirmation
>>> hf buckets delete username/my-bucket

# Skip confirmation
>>> hf buckets delete username/my-bucket --yes

# Don't error if bucket doesn't exist
>>> hf buckets delete username/my-bucket --yes --missing-ok
```

### ファイルの削除

`delete` パラメータを指定して [batch_bucket_files()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.batch_bucket_files) を使用すると、バケットからファイルを削除できます:

```py
>>> from huggingface_hub import batch_bucket_files

# Delete specific files
>>> batch_bucket_files("username/my-bucket", delete=["old-model.bin", "logs/debug.log"])
```

または、`hf buckets rm`(または`hf buckets remove`)によるCLI経由:

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

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

# Remove only files matching a pattern across the entire bucket
>>> hf buckets rm username/my-bucket --recursive --include "*.tmp"

# Exclude specific files from removal
>>> hf buckets rm username/my-bucket/data/ --recursive --exclude "*.safetensors"

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

### バケットを移動する

[move_bucket()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.move_bucket) を使用して、バケットを移動または名前変更できます。同じネームスペース内で名前を変更したり、別のネームスペース（ユーザーまたは組織）に転送したりできます。

```py
>>> from huggingface_hub import move_bucket

# Rename a bucket
>>> move_bucket(from_id="username/old-name", to_id="username/new-name")

# Transfer to an organization
>>> move_bucket(from_id="username/my-bucket", to_id="my-org/my-bucket")
```

または、CLI経由で:

```bash
# Rename a bucket
>>> hf buckets move username/old-bucket username/new-bucket

# Transfer to an organization
>>> hf buckets move username/my-bucket my-org/my-bucket

# Using the hf://buckets/ format
>>> hf buckets move hf://buckets/username/old-bucket hf://buckets/username/new-bucket
```

> [!TIP]
> リポジトリとバケットの移動に関する詳細については、[Hubのドキュメント](https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo)を参照してください。

## バケットの内容を表示

### ファイルの一覧表示

[list_bucket_tree()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.list_bucket_tree) を使用して、バケット内のファイルとディレクトリをリスト表示します。

```py
>>> from huggingface_hub import list_bucket_tree

# List all files
>>> for item in list_bucket_tree("username/my-bucket"):
...     print(item.path, item.size)
file.txt 5
big.bin 2048
sub/nested.txt 14
sub/deep/file.txt 4

# List top-level entries only
>>> for item in list_bucket_tree("username/my-bucket", recursive=False):
...     print(item.type, item.path)
file file.txt
file big.bin
directory sub

# Filter by prefix
>>> for item in list_bucket_tree("username/my-bucket", prefix="sub"):
...     print(item.path)
```

または、CLI経由でも利用でき、テーブル形式、人間が読みやすい形式、ASCIIツリー形式をサポートしています。デフォルトでは、CLIは再帰的ではありません。

```bash
# Default table format (non-recursive, directories shown as entries)
>>> hf buckets list username/my-bucket
        2048  2026-01-15 10:30:00  big.bin
           5  2026-01-15 10:30:00  file.txt
              2026-01-15 10:30:00  sub/

# Recursive listing (all files, including nested)
>>> hf buckets list username/my-bucket -R
        2048  2026-01-15 10:30:00  big.bin
           5  2026-01-15 10:30:00  file.txt
          14  2026-01-15 10:30:00  sub/nested.txt
           4  2026-01-15 10:30:00  sub/deep/file.txt

# Human-readable sizes and short dates
>>> hf buckets list username/my-bucket -R -h
      2.0 KB         Jan 15 10:30  big.bin
         5 B         Jan 15 10:30  file.txt
        14 B         Jan 15 10:30  sub/nested.txt
         4 B         Jan 15 10:30  sub/deep/file.txt

# ASCII tree format
>>> hf buckets list username/my-bucket --tree -h -R
2.0 KB  Jan 15 10:30  ├── big.bin
   5 B  Jan 15 10:30  ├── file.txt
                      └── sub/
                          ├── deep/
   4 B  Jan 15 10:30  │       └── file.txt
  14 B  Jan 15 10:30  └── nested.txt

# Tree structure only (no sizes/dates)
>>> hf buckets list username/my-bucket --tree --quiet -R
├── big.bin
├── file.txt
└── sub/
    ├── deep/
    │   └── file.txt
    └── nested.txt

# Quiet mode: one path per line
>>> hf buckets list username/my-bucket -q
big.bin
file.txt
sub/

# Filter by prefix
>>> hf buckets list username/my-bucket/sub -R
```

> [!TIP]
> `hf buckets list` コマンドは、短縮形式(`username/my-bucket/sub`)と完全なハンドル(`hf://buckets/username/my-bucket/sub`)の両方を引数として受け付けます。

> [!TIP]
> [HfFileSystem](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_file_system#huggingface_hub.HfFileSystem) によるバケットの列挙は、その内容をキャッシュします。他のピアによってバケット内のファイルが追加、更新、削除された際に、列挙が更新されるようにするには、`HfFileSystem(live_follow=True)` を渡してください。[ファイルシステムガイド](./hf_file_system#keep-listings-fresh)を参照してください。

## ファイルのアップロード

### Pythonでアップロード

[batch_bucket_files()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.batch_bucket_files) を使用して、ファイルをバケットにアップロードします。ローカルファイルパスから、または生のバイトからアップロードできます:

```py
>>> from huggingface_hub import batch_bucket_files

# Upload from local file paths
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[
...         ("./model.safetensors", "models/model.safetensors"),
...         ("./config.json", "models/config.json"),
...     ],
... )

# Upload from raw bytes
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[
...         (b'{"key": "value"}', "config.json"),
...     ],
... )
```

`copy` パラメータを使用して、別のバケットまたはリポジトリから xet ファイルをコピーすることもできます。これはサーバーサイドの操作であり、データのダウンロードや再アップロードは行われません。

```python
# Copy files by xet hash (source_repo_type, source_repo_id, xet_hash, destination)
>>> batch_bucket_files(
...     "username/my-bucket",
...     copy=[
...         ("bucket", "username/source-bucket", "<xethash_1>", "models/model.safetensors"),
...         ("model", "username/my-model", "<xethash_2>", "models/config.safetensors"),
...     ],
... )
```

Xetハッシュは`list_repo_tree`を使用して取得できます。

アップロード中にファイルを削除することもできます。

```python
# Upload and delete in one batch
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[("./new-model.safetensors", "model.safetensors")],
...     delete=["old-model.bin"],
... )
```

> [!WARNING]
> [batch_bucket_files()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.batch_bucket_files) への呼び出しはトランザクション的ではありません。処理中にエラーが発生した場合、一部のファイルがアップロード、コピー、または削除された一方で、他のファイルがそうではない可能性があります。サーバーが一部の操作の失敗を報告すると、`BucketBatchError` が発生し、その `failures` 属性に失敗したパスが格納されます。

### CLIで単一のファイルをアップロードする

`hf buckets cp` を使用して、単一のファイルをアップロードします:

> [!TIP]
> `hf buckets cp` は、統合された `hf cp` コマンド（`hf repos cp` としても公開されています）のエイリアスです。これら3つはすべて同一であるため、以下の `hf buckets cp` の例は、`hf cp` でも同様に動作します。

```bash
# Upload to bucket root (uses local filename as remote name)
>>> hf buckets cp ./config.json hf://buckets/username/my-bucket

# Upload to a subdirectory
>>> hf buckets cp ./data.csv hf://buckets/username/my-bucket/logs/

# Upload with a different remote filename
>>> hf buckets cp ./model.safetensors hf://buckets/username/my-bucket/v2/model.safetensors
```

`-` を使用して、コマンドの結果を新しいファイルに直接パイプすることもできます:

```
# Upload from stdin
>>> echo "hello" | hf buckets cp - hf://buckets/username/my-bucket/hello.txt
>>> cat model.safetensors | hf buckets cp - hf://buckets/username/my-bucket/model.safetensors
```

### CLIでディレクトリをアップロードする

`hf buckets sync` を使用して、ローカルディレクトリ全体をバケットにアップロードします:

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

# Upload to a specific prefix in the bucket
>>> hf buckets sync ./data hf://buckets/username/my-bucket/train
```

すべての同期オプションについては、以下の[ディレクトリの同期](#sync-directories)セクションを参照してください。

## ファイルのダウンロード

### Pythonでダウンロード

[download_bucket_files()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.download_bucket_files) を使用して、バケットからファイルをダウンロードします:

```py
>>> from huggingface_hub import download_bucket_files

# Download specific files by path
>>> download_bucket_files(
...     "username/my-bucket",
...     files=[
...         ("models/model.safetensors", "./local/model.safetensors"),
...         ("config.json", "./local/config.json"),
...     ],
... )
```

パフォーマンスを向上させるには、文字列パスの代わりに、[list_bucket_tree()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.list_bucket_tree)から取得した[BucketFile](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.BucketFile)オブジェクトを渡すことができます。これにより、メタデータの取得ステップをスキップできます。

```py
>>> from huggingface_hub import list_bucket_tree, download_bucket_files

# List and filter files, then download
>>> parquet_files = [
...     item for item in list_bucket_tree("username/my-bucket", recursive=True)
...     if item.type == "file" and item.path.endswith(".parquet")
... ]
>>> download_bucket_files(
...     "username/my-bucket",
...     files=[(f, f"./local/{f.path}") for f in parquet_files],
... )
```

### CLIで単一のファイルをダウンロードする

`hf buckets cp` を使用して、単一のファイルをダウンロードします:

```bash
# Download to a specific file
>>> hf buckets cp hf://buckets/username/my-bucket/config.json ./config.json

# Download to a directory (uses original filename)
>>> hf buckets cp hf://buckets/username/my-bucket/config.json ./data/

# Download to current directory (omit destination)
>>> hf buckets cp hf://buckets/username/my-bucket/config.json
```

`-` を使用して、ファイルの内容を `stdout` に直接パイプすることもできます。

```bash
# Download to stdout and pretty-print with jq
>>> hf buckets cp hf://buckets/username/my-bucket/config.json - | jq .
```

### CLIでディレクトリをダウンロード

`hf buckets sync` を使用して、バケット内のすべてのファイルをローカルディレクトリにダウンロードします:

```bash
# Download bucket contents to a local directory
>>> hf buckets sync hf://buckets/username/my-bucket ./data

# Download only a specific prefix
>>> hf buckets sync hf://buckets/username/my-bucket/models ./local-models
```

すべての同期オプションについては、以下の[ディレクトリの同期](#sync-directories)セクションを参照してください。

## ファイルをBucketにコピー

Hubに既にホストされているファイルをBucketにコピーするには、[copy_files()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.copy_files)を使用します:

```py
>>> from huggingface_hub import copy_files

# Bucket to bucket (same or different bucket)
>>> copy_files(
...     "hf://buckets/username/source-bucket/checkpoints/model.safetensors",
...     "hf://buckets/username/destination-bucket/archive/model.safetensors",
... )

# Repo to bucket
>>> copy_files(
...     "hf://datasets/username/my-dataset/processed/",
...     "hf://buckets/username/my-bucket/datasets/processed/",
... )
```

同じ機能は、統合された`hf cp`コマンドを通じてCLIからも利用できます（`hf buckets cp`および`hf repos cp`としても公開されていますが、3つはすべて同一です）：

```bash
# Bucket to bucket
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/destination-bucket/logs/

# Repo to bucket
>>> hf cp hf://username/my-model/config.json hf://buckets/username/my-bucket/models/config.json
```

フォルダをコピーする際、ソースの末尾に`/`がある場合、rsyncスタイルのセマンティクスが適用されます。つまり、フォルダ自体をネストせずに、その*内容*のみがコピーされます。

```bash
# Without trailing slash: "logs" dir is nested => destination/logs/...
>>> hf cp hf://buckets/username/source-bucket/logs hf://buckets/username/destination-bucket/

# With trailing slash: only contents of "logs" are copied => destination/...
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/destination-bucket/
```

注:

- Bucket-to-repo copy はまだサポートされていません。
- サーバーサイドのコピーは、同じ[ストレージリージョン](https://huggingface.co/docs/hub/storage-regions)内でのみ機能します。
- Xetで追跡されているファイル（バケットまたはリポジトリ内）は、ハッシュによってサーバーサイドでコピーされます。データのダウンロードや再アップロードは行われません。
- リポジトリのソースでXetによって管理されていない小さなテキストファイルは、ダウンロードされ、宛先のバケットに再アップロードされます。
- [copy_files()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.copy_files) はリポジトリ間のコピーにも使用できます。詳細については、[リポジトリガイド](./repository#copy-files)を参照してください。

## ディレクトリの同期

`hf buckets sync` コマンド（およびその API 相当の [sync_bucket()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.sync_bucket)）は、ローカルディレクトリとバケット間でファイルを転送する最も強力な方法です。ソースと宛先を比較し、変更されたファイルのみを転送します。

### 基本的な同期

```bash
# Upload: local directory -> bucket
>>> hf buckets sync ./data hf://buckets/username/my-bucket

# Download: bucket -> local directory
>>> hf buckets sync hf://buckets/username/my-bucket ./data
```

> [!TIP]
> `hf sync`は`hf buckets sync`の便利な別名です。両方のコマンドは同一です。
> ```bash
> >>> hf sync ./data hf://buckets/username/my-bucket
> ```

または Python を使用して:

```py
>>> from huggingface_hub import sync_bucket

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

# Download: bucket -> local directory
>>> sync_bucket("hf://buckets/username/my-bucket", "./data")
```

### 不要なファイルを削除する

デフォルトでは、syncはファイルの追加または更新のみを行います。ソースに存在しない宛先のファイルも削除するには、`--delete`（Pythonでは`delete=True`）を使用します:

```bash
# Upload and remove remote files not present locally
>>> hf buckets sync ./data hf://buckets/username/my-bucket --delete

# Download and remove local files not present in bucket
>>> hf buckets sync hf://buckets/username/my-bucket ./data --delete
```

または Python を使用して:

```py
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", delete=True)
>>> sync_bucket("hf://buckets/username/my-bucket", "./data", delete=True)
```

### フィルタリング

include/excludeパターンを使用して、同期するファイルを制御できます:

```bash
# Only sync .txt files
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.txt"

# Exclude log files
>>> hf buckets sync ./data hf://buckets/username/my-bucket --exclude "*.log"

# Combine include and exclude
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"
```

または Python を使用して:

```py
# Only sync .txt files
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", include=["*.txt"])

# Exclude log files
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", exclude=["*.log"])

# Combine include and exclude
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", include=["*.safetensors"], exclude=["*.tmp"])
```

より複雑なフィルタリングには、`--filter-from`（Pythonでは`filter_from`）でフィルタファイルを使用します：

```bash
>>> hf buckets sync ./data hf://buckets/username/my-bucket --filter-from filters.txt
```

フィルターファイルは`+`（インクルード）と`-`（エクスCLUDE）のプレフィックスを使用します。`#`で始まる行はコメントです。ルールは順序通りに評価され（最初に一致したルールが優先されます）：

```text
# filters.txt
- *.log
- *.tmp
+ *.safetensors
+ *.json
```

### 比較モード

デフォルトでは、sync はファイルサイズと修正時刻の両方を比較してファイルを照合します。この動作をカスタマイズできます:

```bash
# Only compare sizes (ignore modification times)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-times

# Only compare modification times (ignore sizes)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-sizes

# Only update files that already exist on the receiver (skip new files)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --existing

# Only create new files (skip files that already exist on the receiver)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existing
```

または Python を使用して:

```py
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_times=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_sizes=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", existing=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_existing=True)
```

### 計画と適用

重要な操作については、実行前に同期計画を確認できます。

```bash
# Step 1: Generate a plan file (nothing is transferred)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl
Sync plan: ./data -> hf://buckets/username/my-bucket
  Uploads: 3
  Downloads: 0
  Deletes: 0
  Skips: 1
Plan saved to: sync-plan.jsonl

# Step 2: Review the plan file (JSONL format)
>>> cat sync-plan.jsonl

# Step 3: Apply the plan
>>> hf buckets sync --apply sync-plan.jsonl
```

または Python を使用して:

```py
# Step 1: Generate a plan file (nothing is transferred)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", plan="sync-plan.jsonl")

# Step 2: Review the plan file (JSONL format), then apply
>>> sync_bucket(apply="sync-plan.jsonl")
```

> [!TIP]
> 計画ファイルは、ヘッダー行の後に各操作が1行ずつ記載されたJSONLファイルです。各操作には、アクション（`upload`、`download`、`delete`、または`skip`）、ファイルパス、およびそのアクションの理由が含まれます。適用する前にこのファイルを手動で編集できますが、構文には注意してください。

### ドライラン

`--dry-run`（Python では `dry_run=True`）を使用すると、何も実行せずに同期プランを取得できます：

```bash
# Preview what would be synced
>>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq '.action'
```

または Python を使用して:

```py
>>> plan = sync_bucket("./data", "hf://buckets/username/my-bucket", dry_run=True)
>>> plan.summary()
{'uploads': 3, 'downloads': 0, 'deletes': 0, 'skips': 1, 'total_size': 4096}
```

> [!TIP]
> `--dry-run` は `--plan` と同じ JSONL 形式を出力しますが、ファイルに保存する代わりに標準出力に表示します。表示されるのは JSONL の内容のみであり、パイプ処理に安全です。

### 冗長モードとサイレントモード

```bash
# Show per-file operations
>>> hf buckets sync ./data hf://buckets/username/my-bucket --verbose

# Suppress all output
>>> hf buckets sync ./data hf://buckets/username/my-bucket --quiet
```

または Python を使用して:

```py
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", verbose=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", quiet=True)
```

## 高度な

より低レベルの使用ケースでは、以下のメソッドも利用できます：

- [get_bucket_paths_info()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.get_bucket_paths_info): バケット内の特定のパスに関する情報を、単一のバッチリクエストで取得します。メタデータが必要なファイルを正確に把握している場合に便利です。

```py
>>> from huggingface_hub import get_bucket_paths_info
>>> for info in get_bucket_paths_info("username/my-bucket", ["file.txt", "models/model.safetensors"]):
...     print(info.path, info.size, info.xet_hash)
```

- [get_bucket_file_metadata()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.get_bucket_file_metadata): 単一のファイルのメタデータ（サイズと xet データ）を取得します。[download_bucket_files()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.download_bucket_files) 内部で使用されます。

```py
>>> from huggingface_hub import get_bucket_file_metadata
>>> metadata = get_bucket_file_metadata("username/my-bucket", "models/model.safetensors")
>>> metadata.size
42000
```