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 обеспечивают объектное хранилище, аналогичное S3, на Hugging Face, работающее на базе системы хранения Xet. В отличие от репозиториев (которые основаны на 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

Удаление файлов

Используйте batch_bucket_files() с параметром delete, чтобы удалить файлы из бакета:

>>> from huggingface_hub import batch_bucket_files

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

Или через CLI с помощью hf buckets rm (или hf buckets remove):

# 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, с поддержкой форматов таблицы, читаемого человеком и ASCII-дерева. По умолчанию CLI работает в нерекурсивном режиме.

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

Вы также можете копировать файлы xet из другого хранилища или репозитория с помощью параметра copy. Это серверная операция — данные не скачиваются и не загружаются повторно:

# 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() не являются транзакционными. Если в процессе возникает ошибка, часть файлов может быть загружена, скопирована или удалена, тогда как другие — нет. Когда сервер сообщает о неудаче некоторых операций, возникает BucketBatchError, в атрибуте failures которого указаны пути к неудавшимся операциям.

Загрузка одного файла с помощью 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

См. раздел Синхронизация каталогов ниже для полного набора вариантов синхронизации.

Загрузка файлов

Загрузка с помощью 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"),
...     ],
... )

Для повышения производительности вместо строковых путей можно передавать объекты BucketFile, полученные с помощью list_bucket_tree(). Это позволяет пропустить этап получения метаданных:

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

См. раздел Синхронизация каталогов ниже для полного набора вариантов синхронизации.

Копирование файлов в Bucket

Используйте copy_files(), чтобы скопировать файлы, уже размещённые на Hub, в Bucket:

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

Примечания:

Копирование из бакета в репозиторий пока не поддерживается.
Копии на стороне сервера работают только в пределах одной и той же области хранения.
Файлы, отслеживаемые с помощью 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 (или delete=True в Python), чтобы также удалять файлы в пункте назначения, которых нет в источнике:

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

Фильтрация

Вы можете управлять синхронизацией файлов с помощью шаблонов включения/исключения:

# 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 (или filter_from в Python):

>>> 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=True в Python), чтобы получить план синхронизации без выполнения каких-либо действий:

# 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 выводит тот же формат JSONL, что и --plan, но печатает его в stdout, а не сохраняет в файл. Печатается только содержимое JSONL, что делает безопасным использование конвейеров (pipe).

Говорливый и тихий режимы

# 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→