Hub Python Library documentation

버킷

Hub Python Library

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

버킷

Buckets는 Xet 스토리지 백엔드를 기반으로 Hugging Face에서 S3와 유사한 객체 스토리지를 제공합니다. 리포지토리(기반이 git이며 파일 히스토리를 추적)와 달리, Buckets는 콘텐츠 주소 기반 중복 제거를 지원하는 대규모 파일을 위한 원격 객체 스토리지 컨테이너입니다. 버전 관리가 필요하지 않은 학습 체크포인트, 로그, 중간 산출물 또는 기타 대규모 파일 컬렉션을 저장하는 등 단순하고 빠르며 변경 가능한 스토리지가 필요한 사용 사례를 위해 설계되었습니다.

Python API(HfApi) 또는 CLI(hf buckets)를 사용하여 버킷과 상호작용할 수 있습니다. 이 가이드에서는 사용 가능한 모든 작업을 안내합니다.

모든 CLI 명령은 hf buckets <command> 아래에서 사용할 수 있습니다. 자세한 내용은 hf buckets --help을 실행하여 확인하세요.

버킷 생성 및 관리

버킷 생성

create_bucket()을 사용하여 버킷을 생성합니다. 버킷 이름을 제공해야 합니다. 네임스페이스를 지정하지 않으면 버킷은 사용자 이름 아래에 생성됩니다.

>>> 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를 통해:

>>> 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 형식도 지정할 수 있습니다:

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

또는 CLI를 통해:

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

버킷 정보 가져오기

버킷의 가시성, 총 크기, 파일 수, 생성 날짜를 포함한 메타데이터를 가져오려면 bucket_info()를 사용합니다.

>>> 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를 통해:

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

버킷 목록

list_buckets()를 사용하여 네임스페이스의 모든 버킷을 나열합니다. 기본적으로 현재 사용자의 네임스페이스에 있는 버킷을 나열합니다.

>>> 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의 약식 표현입니다):

# 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를 사용하여 버킷을 이름으로 필터링할 수도 있습니다:

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

--quiet 및 --format json 옵션을 사용하여 다른 출력 형식을 가져올 수 있습니다. 이는 출력을 grep 또는 jq와 같은 다른 도구로 파이프할 때 특히 유용합니다.

# 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()를 사용하여 기존 버킷을 비공개와 공개로 전환합니다.

>>> 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를 통해:

# 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()를 사용하여 버킷을 삭제합니다. 이 작업은 되돌릴 수 없습니다.

>>> 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를 통해:

# 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()로 버킷에서 파일을 삭제합니다:

>>> 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로:

# 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()를 사용하여 버킷을 이동하거나 이름을 변경할 수 있습니다. 동일한 네임스페이스 내에서 이름을 변경하거나 다른 네임스페이스(사용자 또는 조직)로 이전할 수 있습니다.

>>> 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를 통해:

# 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

리포지토리와 버킷을 이동하는 방법에 대한 자세한 내용은 Hub 문서를 참조하세요.

버킷 내용 탐색

파일 나열

list_bucket_tree()를 사용하여 버킷의 파일과 디렉터리를 나열합니다.

>>> 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를 통해 사용할 수 있으며, table, human-readable, ASCII tree 형식을 지원합니다. 기본적으로 CLI는 비재귀(non-recursive) 방식으로 동작합니다.

# 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

hf buckets list 명령어는 짧은 형식(username/my-bucket/sub)과 전체 핸들(hf://buckets/username/my-bucket/sub)을 모두 인수로 받아들입니다.

HfFileSystem로 버킷을 나열하면 그 내용이 캐시됩니다. 다른 피어에 의해 버킷에서 파일이 추가, 업데이트 및 삭제될 때 나열이 새로 고침되도록 하려면 HfFileSystem(live_follow=True)를 전달하세요. 파일시스템 가이드를 참조하세요.

파일 업로드

Python으로 업로드

batch_bucket_files()를 사용하여 버킷에 파일을 업로드합니다. 로컬 파일 경로 또는 원시 바이트에서 업로드할 수 있습니다:

>>> 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 파일을 복사할 수도 있습니다. 이는 서버 측 작업이며, 데이터가 다운로드되거나 다시 업로드되지 않습니다:

# 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를 사용하여 가져올 수 있습니다.

다른 파일을 업로드하는 동안 파일을 삭제할 수도 있습니다.

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

batch_bucket_files() 호출은 트랜잭션이 아닙니다. 처리 중 오류가 발생하면 일부 파일은 업로드, 복사 또는 삭제되었지만 다른 파일은 그렇지 않은 상태가 될 수 있습니다. 서버가 일부 작업이 실패했다고 보고하면, 실패한 경로가 failures 속성에 포함된 BucketBatchError가 발생됩니다.

CLI로 단일 파일 업로드

hf buckets cp를 사용하여 단일 파일을 업로드합니다:

hf buckets cp는 통합된 hf cp 명령어(또한 hf repos cp로도 노출됨)의 별칭입니다. 세 명령어는 모두 동일하므로, 아래에 있는 hf buckets cp 예제는 hf cp와 함께 사용해도 동일하게 동작합니다.

# 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를 사용하여 로컬 디렉터리 전체를 버킷에 업로드합니다:

# 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()를 사용하여 버킷에서 파일을 다운로드합니다:

>>> 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()에서 가져온 BucketFile 객체를 전달할 수 있습니다. 이렇게 하면 메타데이터 가져오기 단계를 건너뜁니다:

>>> 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를 사용하여 단일 파일을 다운로드합니다:

# 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으로 직접 파이프할 수도 있습니다:

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

CLI로 디렉터리 다운로드

hf buckets sync를 사용하여 버킷의 모든 파일을 로컬 디렉터리로 다운로드합니다:

# 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 섹션을 참조하세요.

Copy files to Bucket

Hub에 이미 호스팅된 파일을 Bucket으로 복사하려면 copy_files()를 사용하세요:

>>> 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/",
... )

CLI에서는 통합된 hf cp 명령을 통해 동일한 기능을 사용할 수 있습니다(hf buckets cp 및 hf repos cp로도 노출되며, 세 명령은 모두 동일합니다):

# 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 스타일 의미론이 적용됩니다. 즉, 폴더 자체를 중첩하지 않고 폴더의 내용물만 복사됩니다:

# 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 복사는 아직 지원되지 않습니다.
서버 측 복사본은 동일한 스토리지 리전 내에서만 작동합니다.
Xet로 추적되는 파일(버킷 또는 저장소 내)은 해시로 서버 측에서 복사되며, 데이터가 다운로드되거나 다시 업로드되지 않습니다.
Xet으로 추적되지 않는 리포지토리 소스의 작은 텍스트 파일은 다운로드된 후 대상 버킷에 다시 업로드됩니다.
copy_files()는 저장소 간 복사에도 사용할 수 있습니다. 자세한 내용은 저장소 가이드를 참고하세요.

디렉터리 동기화

hf buckets sync 명령어(그리고 해당 API인 sync_bucket())는 로컬 디렉터리와 버킷 간 파일을 전송하는 가장 강력한 방법입니다. 소스와 대상의 차이를 비교하여 변경된 파일만 전송합니다.

기본 동기화

# 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

hf sync은 hf buckets sync의 편리한 별칭입니다. 두 명령어는 동일합니다.
>>> hf sync ./data hf://buckets/username/my-bucket

또는 Python을 통해:

>>> 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)를 사용하세요:

# 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을 통해:

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

필터링

include/exclude 패턴을 사용하여 동기화할 파일을 제어할 수 있습니다:

# 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을 통해:

# 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)를 사용하여 필터 파일을 지정합니다:

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

필터 파일은 +(포함) 및 -(제외) 접두사를 사용합니다. #로 시작하는 줄은 주석입니다. 규칙은 순서대로 평가되며(첫 번째 일치하는 규칙이 우선합니다):

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

비교 모드

기본적으로 sync는 파일 크기와 수정 시간을 모두 사용하여 파일을 비교합니다. 이 동작을 사용자 정의할 수 있습니다:

# 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을 통해:

>>> 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)

계획 및 적용

중요한 작업의 경우, 실행 전에 동기화 계획을 검토할 수 있습니다:

# 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을 통해:

# 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")

플랜 파일은 헤더 줄을 포함하고 각 연산별로 한 줄씩 구성된 JSONL 파일입니다. 각 연산에는 액션(upload, download, delete, 또는 skip), 파일 경로, 그리고 해당 액션의 이유가 포함됩니다. 적용하기 전에 이 파일을 수동으로 편집할 수 있지만 구문에 주의하세요.

Dry run

--dry-run(또는 Python에서 dry_run=True)를 사용하면 실행 없이 동기화 계획을 확인할 수 있습니다:

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

또는 Python을 통해:

>>> 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}

--dry-run은 --plan과 동일한 JSONL 형식을 출력하지만, 파일에 저장하는 대신 stdout으로 출력합니다. JSONL 내용만 출력되므로 파이프 처리에 안전합니다.

상세 모드와 조용한 모드

# 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을 통해:

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

고급

낮은 수준의 사용 사례를 위해 다음 메서드도 사용할 수 있습니다:

get_bucket_paths_info(): 단일 배치 요청으로 버킷 내 특정 경로에 대한 정보를 가져옵니다. 메타데이터가 필요한 파일이 정확히 무엇인지 알고 있을 때 유용합니다.

>>> 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(): 단일 파일의 메타데이터(크기 및 xet 데이터)를 가져옵니다. download_bucket_files() 내부에서 사용됩니다.

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

Update on GitHub

←파일 업로드 CLI 사용→