Início rápido

O Hugging Face Hub é o principal local para compartilhar modelos de machine learning, demonstrações, conjuntos de dados e métricas. A biblioteca huggingface_hub ajuda você a interagir com o Hub sem sair do seu ambiente de desenvolvimento. Você pode criar e gerenciar repositórios facilmente, baixar e enviar arquivos e obter metadados úteis de modelos e conjuntos de dados do Hub.

Instalação

Para começar, instale a biblioteca huggingface_hub:

pip install --upgrade huggingface_hub

Para mais detalhes, consulte o guia de instalação.

O huggingface_hub também inclui uma CLI hf que permite interagir com o Hub diretamente pelo terminal. Se você estiver usando agentes de IA (Claude Code, Codex, Cursor, ...), instale o Skill para permitir que seu agente use a CLI:

Copiado

# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add

Confira o guia Hugging Face CLI for AI Agents para mais detalhes.

Baixar arquivos

Os repositórios no Hub são controlados por versão com git, e os usuários podem baixar um arquivo individual ou o repositório inteiro. Você pode usar a função hf_hub_download() para baixar arquivos. Essa função baixa e faz o cache de um arquivo no seu disco local. Da próxima vez que você precisar desse arquivo, ele será carregado do seu cache, então você não precisa baixá-lo novamente.

Você precisará do id do repositório e do nome do arquivo do arquivo que deseja baixar. Por exemplo, para baixar o arquivo de configuração do modelo Pegasus:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")

Para baixar uma versão específica do arquivo, use o parâmetro revision para especificar o nome da branch, a tag ou o hash do commit. Se você optar por usar o hash do commit, ele deve ser o hash de comprimento completo, em vez do hash de commit curto de 7 caracteres:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
...     repo_id="google/pegasus-xsum",
...     filename="config.json",
...     revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )

Para mais detalhes e opções, consulte a referência da API de hf_hub_download().

Autenticação

Em muitos casos, é necessário estar autenticado com uma conta do Hugging Face para interagir com o Hub: baixar repositórios privados, enviar arquivos, criar PRs, etc. Crie uma conta se você ainda não tiver uma.

Comando de login

A maneira mais fácil de autenticar é com o comando login():

hf auth login

Se você já estiver conectado, o comando será retornado imediatamente. Para forçar o relogin, use hf auth login --force. Se você não estiver conectado, será solicitado que faça login pelo navegador: abra a URL impressa, insira o código curto, aprove a solicitação e um token de acesso será obtido e salvo no seu diretório HF_HOME (padrão é ~/.cache/huggingface/token). O token expira após um tempo, mas é renovado automaticamente, desde que você continue usando-o. Qualquer script ou biblioteca que interaja com o Hub usará esse token ao enviar solicitações. Alternativamente, você pode colar um User Access Token gerado a partir da sua página de Configurações.

Os User Access Tokens podem ter permissões de read ou write. Certifique-se de ter um token de acesso write se quiser criar ou editar um repositório. Caso contrário, é melhor gerar um token read para reduzir o risco em caso de vazamento acidental do seu token.

Alternativamente, você pode fazer login programaticamente usando login() em um notebook ou script:

>>> from huggingface_hub import login
>>> login()

Você só pode estar conectado a uma conta por vez. Fazer login em uma nova conta deslogará automaticamente da anterior. Para determinar sua conta ativa atual, basta executar o comando hf auth whoami.

Uma vez conectado, todas as solicitações ao Hub - mesmo métodos que não necessariamente exigem autenticação - usarão seu token de acesso por padrão. Se você deseja desabilitar o uso implícito do seu token, deve definir HF_HUB_DISABLE_IMPLICIT_TOKEN=1 como uma variável de ambiente (veja referência).

Gerenciar vários tokens localmente

Você pode salvar vários tokens em sua máquina simplesmente fazendo login com o comando login() para cada token. Se você precisar alternar entre esses tokens localmente, pode usar o comando auth switch:

hf auth switch

Este comando solicitará que você selecione um token pelo nome a partir de uma lista de tokens salvos. Uma vez selecionado, o token escolhido se torna o token ativo e será usado para todas as interações com o Hub.

Você pode listar todos os tokens de acesso disponíveis na sua máquina com hf auth list.

Variável de ambiente

A variável de ambiente HF_TOKEN também pode ser usada para autenticar você. Isso é especialmente útil em um Space, onde você pode definir HF_TOKEN como um segredo de Space.

NOVO: O Google Colaboratory permite definir chaves privadas para seus notebooks. Defina um segredo HF_TOKEN para ser autenticado automaticamente!

A autenticação por meio de uma variável de ambiente ou de um segredo tem prioridade sobre o token armazenado na sua máquina.

Parâmetros do método

Por fim, também é possível autenticar passando seu token para qualquer método que aceite token como parâmetro.

from huggingface_hub import whoami

user = whoami(token=...)

Isso geralmente é desencorajado, exceto em um ambiente em que você não deseja armazenar seu token permanentemente ou se precisa lidar com vários tokens ao mesmo tempo.

Tenha cuidado ao passar tokens como parâmetro. A melhor prática é sempre carregar o token de um cofre seguro, em vez de codificá-lo diretamente no seu código ou notebook. Tokens codificados diretamente no código representam um risco significativo de vazamento caso você compartilhe seu código inadvertidamente.

Criar um repositório

Depois de se registrar e fazer login, crie um repositório com a função create_repo():

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")

Se você deseja que seu repositório seja privado, então:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)

Repositórios privados não serão visíveis para ninguém, exceto para você.

Para criar um repositório ou enviar conteúdo para o Hub, você deve fornecer um User Access Token que tenha a permissão write. Você pode escolher a permissão ao criar o token em sua página de Configurações.

Enviar arquivos

Use a função upload_file() para adicionar um arquivo ao seu repositório recém-criado. Você precisa especificar:

1. O caminho do arquivo a ser enviado.
2. O caminho do arquivo no repositório.
3. O id do repositório onde você deseja adicionar o arquivo.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/home/lysandre/dummy-test/README.md",
...     path_in_repo="README.md",
...     repo_id="lysandre/test-model",
... )

Para enviar mais de um arquivo por vez, consulte o guia Upload, que apresentará vários métodos para envio de arquivos (com ou sem git).

Próximas etapas

A biblioteca huggingface_hub oferece uma maneira fácil para os usuários interagir com o Hub em Python. Para saber mais sobre como você pode gerenciar seus arquivos e repositórios no Hub, recomendamos ler nossos guias de como fazer para:

• Gerencie seu repositório.
• Baixe arquivos do Hub.
• Envie arquivos para o Hub.
• Busque no Hub pelo modelo ou conjunto de dados desejado.
• Executar Inferência em vários serviços para modelos hospedados no Hugging Face Hub.