Buckets de Armazenamento

Storage Buckets são um tipo de repositório no Hugging Face Hub que oferece armazenamento de objetos semelhante ao S3, impulsionado pelo backend de armazenamento Xet. Diferentemente dos repositórios baseados em Git (modelos, datasets, Spaces), os buckets são sem versionamento e mutáveis, projetados para casos de uso em que você precisa de armazenamento simples e rápido, como checkpoints de treinamento, logs, artefatos intermediários ou qualquer grande coleção de arquivos que não necessite de controle de versão.

Você pode interagir com os buckets usando a interface web do Hub, o hf CLI ou a API em Python.

Os Buckets estão disponíveis para todos os usuários e organizações. Consulte hf.co/storage para obter detalhes de preços.

Consulte o Guia de Migração para mover dados existentes para um bucket a partir do disco local, de outra nuvem ou do Hub, Padrões de Acesso para saber como acessar os dados do bucket a partir das suas ferramentas (montagem como sistema de arquivos, caminhos hf://, montagem de volumes em Jobs/Spaces), a API Compatível com S3 para usar ferramentas S3 existentes (AWS CLI, boto3, s5cmd) e Integrações de Bucket para bibliotecas com suporte nativo a buckets (como datatrove, LeRobot e Trackio) e trechos de código para bibliotecas de dados como pandas, Dask e Spark.

Buckets vs Repositórios

O Hub oferece dois tipos de armazenamento: repositórios baseados em Git para trabalho colaborativo com controle de versão e buckets para armazenamento de objetos mutável e de alta velocidade.

Use repositórios quando você quiser histórico de versões, recursos de colaboração (PRs, discussões) e integrações com bibliotecas. Use buckets quando precisar de armazenamento rápido e mutável para dados que mudam com frequência — os arquivos podem ser sobrescritos ou excluídos no local.

Criando um Bucket

Da interface do Hub

1. Acesse huggingface.co/new-bucket:

2. Especifique o proprietário do bucket: pode ser você ou qualquer uma das organizações às quais você está vinculado.

3. Insira um nome de bucket.

4. Escolha se o bucket deve ser público ou privado.

5. Opcionalmente, pré-selecione as regiões de pré-aquecimento de CDN para armazenar em cache seus dados mais perto do seu ambiente de computação desde o início.

Após criar o bucket, você deve ver a página do bucket:

Da 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

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

Alterando a visibilidade

Você pode alterar a visibilidade de um bucket após a criação:

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

Para a referência completa da API em Python, incluindo a exclusão, o movimento e a listagem de buckets, consulte o guia de Buckets do huggingface_hub.

Navegando por Buckets no Hub

Cada bucket possui uma página no Hub onde você pode navegar pelo seu conteúdo, explorar diretórios e ver os detalhes dos arquivos. As páginas de buckets estão disponíveis em https://huggingface.co/buckets/<owner>/<bucket-name>.

Renderização do README

Se um diretório no seu bucket contiver um arquivo README.md, o Hub o exibirá abaixo da lista de arquivos na página desse diretório. Isso funciona tanto na raiz do bucket quanto em qualquer subdiretório — útil para documentar o que um bucket contém, como os dados estão organizados ou como as ferramentas de nível inferior devem consumi-los.

Listagem a partir da CLI

Você também pode listar o conteúdo do bucket pela 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
...

Gerenciando Arquivos

Você pode fazer upload e download de arquivos diretamente da página do bucket no Hub, ou usar a CLI e a API em Python para acesso programático. Os arquivos do bucket são referenciados usando caminhos hf://buckets/ (por exemplo, hf://buckets/username/my-bucket/path/to/file). O comando hf buckets cp trata transferências de arquivos individuais, enquanto o hf buckets sync é mais adequado para diretórios. Todos os comandos funcionam em ambas as direções — de local para remoto e de remoto para local.

Se seus dados já estão em um repositório de modelo, dataset ou Space (ou em outro bucket), você pode copiá-los no servidor com hf buckets cp — sem necessidade de download ou reenvio. Consulte Copiar arquivos entre repositórios e buckets.

Enviando arquivos

Para uploads rápidos, você pode arrastar e soltar arquivos diretamente na página do bucket no seu navegador. Para uso programático, hf buckets cp copia arquivos individuais para um bucket. A origem é um caminho local e o destino é um caminho hf://buckets/. Você também pode encaminhar dados do stdin, o que é útil para conteúdo gerado programaticamente.

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

Em Python, use batch_bucket_files para enviar um ou mais arquivos em uma única chamada. Cada entrada é uma tupla de (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"),
    ],
)

Para mais opções de upload (bytes brutos, upload+exclusão combinados, etc.), consulte o guia de upload do huggingface_hub.

Baixando arquivos

Você pode baixar arquivos individuais diretamente da página do bucket no Hub clicando neles. Para acesso programático, o download espelha a sintaxe de upload — basta trocar a origem e o destino em hf buckets cp. Você também pode transmitir um arquivo para o stdout usando - como destino, o que permite encaminhar o conteúdo do bucket diretamente para outras ferramentas.

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 .

Em Python, use download_bucket_files com uma lista de tuplas (remote_path, local_path).

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

Para downloads mais rápidos usando metadados pré-obtidos, consulte o guia de download do huggingface_hub.

Sincronizando diretórios

O comando sync funciona como rsync ou aws s3 sync — ele compara a origem e o destino e transfere apenas os arquivos que foram alterados. Essa é a maneira mais eficiente de manter um diretório local e um bucket sincronizados. Por padrão, o sync apenas adiciona e atualiza arquivos. Passe --delete para também remover arquivos no destino que não existem mais na origem. Use --dry-run para visualizar o que aconteceria sem realmente transferir nada.

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 é um alias conveniente para 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")

O comando sync suporta filtragem (--include, --exclude), modos de comparação (--ignore-times, --existing) e um fluxo de trabalho de planejar e aplicar para revisar as operações antes de executá-las. Para o conjunto completo de opções, consulte o guia de sincronização do huggingface_hub.

Excluindo arquivos

Como os buckets não são versionados, as exclusões são imediatas e permanentes — não há como recuperar um arquivo excluído. Use --dry-run para verificar novamente antes de remover arquivos, especialmente ao usar --recursive.

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

Para mais opções de exclusão (filtragem baseada em padrões, remoção recursiva, etc.), consulte o guia de exclusão do huggingface_hub.

Copiando arquivos entre repositórios e buckets

Você pode copiar arquivos rastreados por Xet de qualquer repositório (modelo, conjunto de dados, Space) ou bucket para um bucket de destino sem reenviar os dados. A cópia é feita no lado do servidor: apenas os hashes de conteúdo do Xet são migrados, de modo que até mesmo arquivos muito grandes são copiados instantaneamente graças à deduplicação em nível de chunk.

Apenas arquivos rastreados pelo Xet são copiados de servidor para servidor. Arquivos não-Xet pequenos (por exemplo, arquivos de configuração e READMEs) são baixados e reenviados automaticamente. A cópia no servidor também exige que a origem e o destino estejam na mesma região de armazenamento.

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

Você precisa de acesso de leitura ao repositório ou bucket de origem e acesso de gravação ao bucket de destino.

Observe que a transferência de dados no sentido inverso, de um bucket para um repositório (modelo, dataset, Space), sem reenvio, ainda não está disponível, mas está no roadmap.

Acompanhando Alterações

Buckets são mutáveis, portanto, ferramentas que mantêm uma visão de um bucket — montagens, camadas de sistema de arquivos, demônios de sincronização, painéis — precisam saber quando os arquivos são alterados. Dois mecanismos estão disponíveis:

• Webhooks: callbacks HTTP para um servidor que você controla, ou um Job iniciado a cada alteração — veja Process new files in a bucket with Jobs.
• Acompanhamento ao vivo: um fluxo de eventos enviados pelo servidor ao qual seu cliente se inscreve.

Acompanhamento ao vivo

GET https://huggingface.co/api/buckets/<owner>/<bucket-name>/events transmite as alterações de arquivos de um bucket como server-sent events. A solicitação deve incluir Accept: text/event-stream (caso contrário, retorna um 400) e requer o mesmo acesso de leitura que a listagem do bucket — nenhum token é necessário para um bucket público. Consulte a OpenAPI spec para o esquema completo de parâmetros e respostas.

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

Em Python, você não precisa consumir o stream manualmente. HfFileSystem o acompanha para você com live_follow=True, de modo que suas listagens em cache permanecem atualizadas quando outro processo altera o bucket:

Copiado

from huggingface_hub import HfFileSystem

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

Bibliotecas que aceitam storage_options do fsspec (pandas, PyArrow, …) também o aceitam.

O stream emite quatro tipos de eventos:

Cada entrada em changes tem um path e um op (add, update ou delete). Um add ou update também carrega os campos que mudaram — size, xetHash, uploadedAt, mtime, mtimeNanos — de modo que um update pode ser tão pequeno quanto um novo uploadedAt quando um arquivo foi reenviado de forma idêntica. Campos que não mudaram são omitidos; mtime/mtimeNanos também podem ser null quando um upload os limpou, então trate ausentes e null da mesma forma.

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

Retomando. Um novo stream começa no momento em que você se conecta. Para também obter as alterações que você perdeu, passe o último cursor recebido (cada evento ready e changes carrega um) como ?cursor=<cursor>, ou um timestamp como ?since=<ISO timestamp> (inclusivo, por exemplo, 2026-09-16T09:21:45Z).

Apenas as últimas ~15 minutos de alterações podem ser reproduzidas. Se o seu cursor ou since for mais antigo que isso, você recebe reset em vez de uma reprodução: liste o bucket uma vez para reconstruir sua visão e, em seguida, siga novamente a partir do cursor do evento ready do novo stream. Retomar é destinado a cobrir lacunas curtas, como uma conexão perdida ou uma reinicialização; um cliente que esteve ausente por mais tempo deve esperar relistar.

Reconectando. Conexões de longa duração são recicladas: aproximadamente a cada 20 minutos (e durante implantações), o servidor envia reconnect e então encerra o stream. Trate qualquer encerramento do stream da mesma forma — reconecte com o último cursor recebido. Um comentário : ping é enviado a cada 30 segundos para manter a conexão ativa, portanto, um stream que fica completamente silencioso pode ser considerado morto.

Uma resposta 503 significa que o acompanhamento ao vivo está momentaneamente indisponível — tente novamente após o atraso indicado no cabeçalho Retry-After.

Pré-aquecimento e CDN

Os buckets ficam, por padrão, no armazenamento global do Hub. Para cargas de trabalho em que a localização do armazenamento afeta diretamente a taxa de transferência, você pode pré-aquecer os dados do bucket para trazê-los mais perto do seu ambiente de computação.

O Pre-warming faz o pré-aquecimento dos arquivos em locais de borda próximos a provedores de nuvem e regiões específicos, para que seus jobs leiam os dados localmente em vez de buscá-los entre regiões. Isso é especialmente útil para:

• Clusters de treinamento que precisam de acesso rápido a grandes conjuntos de dados ou checkpoints
• Configurações multi-região em que diferentes partes de um pipeline são executadas em diferentes nuvens
• Distribuindo artefatos grandes para muitos consumidores em todo o mundo

Consulte hf.co/storage para ver as regiões disponíveis e os detalhes sobre como ativar o pré-aquecimento.

Casos de Uso

Pontos de verificação e registros de treinamento

Ao executar tarefas de treinamento (por exemplo, via Jobs), salve checkpoints e logs em um bucket. Diferente de um repositório Git, você pode sobrescrever o checkpoint mais recente sem acumular histórico de versões, e o sync garante que apenas os dados alterados sejam transferidos.

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

Como os buckets são construídos sobre o Xet, checkpoints sucessivos em que grandes partes do modelo estão congeladas se beneficiam da deduplicação em nível de chunk. Apenas os chunks alterados são enviados.

Em Jobs, você também pode montar o bucket e gravar checkpoints diretamente nele. Consulte Train models on Jobs.

Pipelines de processamento de dados

Buckets funcionam como áreas de armazenamento temporário para fluxos de trabalho de processamento de dados. Processe dados brutos, escreva saídas intermediárias em um bucket e, quando o pipeline for concluído, promova o artefato final para um repositório Dataset versionado. Isso mantém seu repositório versionado limpo, ao mesmo tempo que oferece armazenamento mutável e rápido para seu pipeline. O datatrove suporta esse padrão diretamente.

Observe que a transferência de dados de um Bucket para um repositório sem reenvio ainda não está disponível, mas está no roteiro.

Armazenamento agêntico

Agentes de IA precisam de armazenamento temporário para resultados intermediários, saídas de ferramentas, rastros e memória de trabalho. Os buckets oferecem um local nativo do Hub para esses dados: acesso mutável rápido sem a sobrecarga do Git, permissões padrão do Hugging Face e endereçáveis por meio de caminhos hf://buckets/ em todo o ecossistema do Hub.

Backups rotativos

Buckets são adequados para manter backups contínuos. Com um repositório Dataset baseado em Git, a exclusão de arquivos obsoletos não libera armazenamento — o histórico do Git retém todas as versões anteriores, portanto, seria necessário compactar commits ou reescrever o histórico para realmente recuperar espaço. Com buckets, os arquivos antigos são realmente removidos após a exclusão, e você paga apenas pelo que está atualmente armazenado.

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

Vinculando modelos a buckets

Você pode criar um link bidirecional entre um modelo e um bucket adicionando o campo buckets aos metadados do cartão do modelo. Os modelos vinculados então aparecerão na página do bucket, e o bucket aparecerá como uma tag na página do modelo.

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

Consulte Especificando um bucket na documentação dos cartões de modelo para mais detalhes.

Preços

Os Storage Buckets são cobrados com base na quantidade de dados armazenados, com uma cobrança simples por TB. Os planos Enterprise se beneficiam de uma cobrança baseada em deduplicação, na qual os blocos compartilhados entre arquivos reduzem diretamente o volume cobrado.

Quanto a outros repositórios, os buckets podem ser criados gratuitamente e possuem uma cota de armazenamento gratuita. Para o uso acima da faixa gratuita, consulte hf.co/storage. Para informações gerais de faturamento, consulte a documentação de Billing.