Token do Hugging Face: Como Criar, Armazenar e Usá-lo

Um token do Hugging Face é um User Access Token que autentica sua máquina, script ou job de CI no Hugging Face Hub. Você cria um nas configurações da sua conta na aba Access Tokens , escolhe um papel (leem, write ou fine-grained), depois executa hf auth login e cola-o ou define HF_TOKEN no seu ambiente. Os tokens parecem com hf_....

O que o token realmente autoriza

Três coisas, na prática: baixar arquivos de repositórios privados ou com acesso restrito, fazer upload de arquivos para repositórios que você pode escrever, e chamar Provedores de Inferência como um token bearer. Pesos de modelos públicos não precisam de nenhum token — hf download gpt2 config.json funciona sem autenticação.

A documentação do Hugging Face descreve o token como usável «no lugar de uma senha» para git e autenticação básica, que é o modelo mental correto: é uma credencial, não uma chave de API vinculada a um produto.

Os três tipos de token

Função	Permissões	Use para
leem	Acesso de leitura a todos os repositórios que você já pode ler, incluindo repositórios privados que você ou suas organizações possuem	Baixar pesos com acesso restrito, executar inferência, notebooks
write	Tudo leem faz, mais acesso de escrita a repositórios que você pode escrever	Fazer upload de checkpoints, editar cartões de modelo, execuções de treinamento que fazem upload
fine-grained	Apenas os recursos específicos e permissões que você marca	Aplicações de produção, CI, qualquer coisa compartilhada com um time

Hugging Face explicitamente recomenda tokens de granularidade fina para uso em produção, pelo motivo de que o raio de explosão se um vazar é menor e pode ser compartilhado dentro de uma organização sem expor sua conta inteira. Um padrão típico de produção: um membro da org solicita acesso a um modelo bloqueado, depois cria um token de granularidade fina com acesso de leitura para esse repositório apenas.

Criando um token, passo a passo

1. Faça login, clique no seu avatar (canto superior direito) → Settings.
2. Abra o arquivo Access Tokens aba — URL direto huggingface.co/settings/tokens.
3. Clique New token.
4. Nomeie-o de acordo com a máquina ou app que o armazenará (laptop-read, ci-push), não de acordo com você mesmo. Um token por uso é a prática recomendada documentada, para que você possa revogar um sem quebrar o resto.
5. Escolha o papel. Para granularidade fina, marque as permissões individuais.
6. Copie o valor imediatamente. Depois você só pode deletá-lo ou atualizá-lo da mesma página via Manage.

Se você está em uma org Team ou Enterprise com uma política de tokens, um token de granularidade fina com escopo para essa org pode cair em estado Pending até que um admin o aprove — a lista de tokens mostra uma ampulheta laranja ao lado dele, e chamadas contra recursos da org retornam 403 até aprovação.

Fazendo login pelo terminal

O CLI enviado com huggingface_hub é chamado hf. Instale e faça login:

pip install huggingface_hub
hf auth login

Por padrão isso agora executa um fluxo de dispositivo de navegador: imprime uma URL (https://huggingface.co/oauth/device) e um código curto como ABCD-EFGH. Aprove-o no navegador e o CLI salva um token chamado oauth-<username> que se atualiza enquanto você continuar usando-o. Escolher Paste an access token em vez disso permite que você forneça um token que você criou manualmente.

Nota sobre nomenclatura: tutoriais mais antigos usam huggingface-cli login. O conjunto de comandos foi reorganizado sob hf auth ..., e qual grafia sua máquina aceita depende da huggingface_hub versão instalada — execute hf --help para ver o que você realmente tem.

Comando	O que faz
hf auth login --token $HF_TOKEN	Login não interativo, seguro para scripts
hf auth login --token $HF_TOKEN --add-to-git-credential	Também escreve o token no seu git credential helper
hf auth login --force	Faça login novamente mesmo se já autenticado
hf auth whoami	Imprime seu nome de usuário e orgs; retorna erro se não autenticado
hf auth list	Lista os nomes de tokens armazenados na máquina
hf auth switch --token-name NAME	Alterna o token ativo
hf auth token	Imprime o token ativo para stdout
hf auth logout --token-name NAME	Deleta um token armazenado (omita a flag para deletar todos)
hf env	Despeja o caminho do token, se um token está salvo, e git helpers configurados

Passe o token via $HF_TOKEN em vez de digitar a string literal — os docs alertam contra colar tokens brutos em linhas de comando onde histórico de shell e logs de CI podem capturá-los.

Onde o token é armazenado

Múltiplos tokens nomeados vivem em um arquivo stored_tokens ; o ativo no momento é espelhado para um simples token arquivo. Ambos ficam sob HF_HOME, que assume como padrão ~/.cache/huggingface.

Linux

~/.cache/huggingface/token e ~/.cache/huggingface/stored_tokens. Se XDG_CACHE_HOME estiver definido e HF_HOME não estiver, a base se torna $XDG_CACHE_HOME/huggingface em vez disso.

macOS

Igual ao Linux: ~/.cache/huggingface/token. Hugging Face não usa ~/Library/Caches aqui, então não procure lá.

Windows

O caminho se resolve a partir do seu diretório pessoal: C:Users<você>.cachehuggingfacetoken. Duas particularidades específicas do Windows que valem a pena conhecer. Primeiro, o cache do modelo usa symlinks, que exigem Modo de Desenvolvedor ou um shell de administrador; sem eles você recebe um aviso e arquivos duplicados no disco, silenciável com HF_HUB_DISABLE_SYMLINKS_WARNING=1. Segundo, se você apontar HF_HUB_CACHE para um NAS compartilhado com máquinas Linux, defina HF_HUB_DISABLE_SYMLINKS=1 — symlinks gravados no Linux não são confiávelmente navegáveis no Windows.

As variáveis de ambiente que importam

Variável	Efeito	Padrão
HF_TOKEN	Fornece o token; sobrescreve o token armazenado em disco	não definida
HF_TOKEN_PATH	Onde o arquivo de token é lido e gravado	$HF_HOME/token
HF_HOME	Pasta base para token mais cache	~/.cache/huggingface
HF_HUB_DISABLE_IMPLICIT_TOKEN	Impede que o token seja anexado a solicitações de leitura que não o precisam; ele é então enviado apenas para chamadas de escrita	desativado
HUGGING_FACE_HUB_TOKEN	Alias descontinuado — ainda funciona, mas não tem mais precedência sobre HF_TOKEN	—

Duas pegadinhas. Essas variáveis são lidas no tempo de importação de huggingface_hub, portanto definir uma após a importação não tem efeito — reinicie o kernel. E hf auth logout não consegue fazer logout de um token fornecido via HF_TOKEN; você tem que desmarcar a variável.

Usando o token com git

Clonar repos grandes via HTTPS solicita uma senha — forneça o token, não sua senha de conta:

git clone https://huggingface.co/<user>/<repo>
# Username: your-hf-username
# Password: hf_...

Para evitar redigitar, faça login com --add-to-git-credential, que passa o token para seu helper configurado (store no Linux, Keychain no macOS, Windows Credential Manager no Windows). Confirme o que está conectado com hf env, que imprime uma linha Configured git credential helpers .

Usando o token para inferência hospedada

O mesmo token é a credencial bearer para Inference Providers, que expõe um endpoint compatível com OpenAI em https://router.huggingface.co/v1:

curl https://router.huggingface.co/v1/chat/completions 
    -H "Authorization: Bearer $HF_TOKEN" 
    -H 'Content-Type: application/json' 
    -d '{"model": "openai/gpt-oss-120b", "messages": [{"role": "user", "content": "hello"}]}'

Para este caminho, um token refinado com a permissão Make calls to Inference Providers é o mais apropriado. Na faturação, Hugging Face publica créditos mensais de $0,10 para contas gratuitas, $2,00 para PRO e $2,00 por membro para orgs Team e Enterprise, depois você paga conforme usa com as taxas do próprio provedor sem markup da HF. Orgs Team e Enterprise podem centralizar a faturação enviando X-HF-Bill-To: my-org-name como cabeçalho enquanto cada membro mantém seu próprio token.

Esses créditos se esgotam rapidamente com taxas de modelos de ponta — um modelo com preço como Claude Opus 5 a $5,00 de entrada / $25,00 de saída por 1M de tokens custa $2,00 em aproximadamente 80k tokens de saída. Modelos open-weights são uma ordem de grandeza diferente: Llama 3.3 70B custa $0,10 entrada / $0,32 saída por 1M tokens, e Llama 3.1 8B $0,02 entrada / $0,03 saída. Calcule o modelo Calculadora de custos de API contra seu volume de tokens antes de encadear um token em qualquer coisa que seja cíclica.

Modelos com acesso restrito: o token é necessário mas não suficiente

Para repositórios restritos — a maioria dos lançamentos Llama e Gemma — um token válido carrega apenas o acesso que você já recebeu. De acordo com a documentação de modelos restritos do Hugging Face, a própria solicitação de acesso «só pode ser feita a partir do seu navegador»: abra a página do modelo enquanto conectado, complete o formulário, clique em Concordo. A aprovação é automática ou manual, e os autores podem revogá-la depois sem aviso. Somente então hf auth login desbloqueia o download em um script. Normalmente você verá um 401 quando nenhum token é enviado e um 403 quando o token é válido mas sua conta não tem acesso.

Quando você não precisa de um token

Pesos públicos sem restrições baixam sem credenciais, então uma pilha puramente local muitas vezes não precisa de token. Ollama extrai do seu próprio registro inteiramente, e llama.cpp ou LM Studio podem buscar GGUFs públicos anonimamente. O que decide sua configuração é memória, não autenticação: Llama 3.1 8B precisa de cerca de 5 GB de VRAM a 4-bit e Llama 3.3 70B de cerca de 40 GB, enquanto DeepSeek R1 quer aproximadamente 400 GB e Kimi K3 cerca de 1,4 TB — território de cluster. Verifique a sua contra calculadora de VRAM ou o tabela de requisitos de VRAM por modelo.

Solução de problemas

Sintoma	Provável causa	Corrigir
401 Unauthorized	Nenhum token enviado, ou foi deletado no servidor	hf auth whoami; execute hf auth login --force
403 em um repositório restrito	Token está ok; conta não tem acesso	Solicite acesso no navegador na página do modelo
403 com «revogado pelo administrador da organização»	Organização empresarial revogou o token — permanente	Delete-o e crie um novo
Funciona no shell, falha no notebook	HF_TOKEN configurado após import, ou um ambiente de kernel diferente	Reinicie o kernel; verifique com hf env
Seus modelos privados desaparecendo de uma listagem	HF_HUB_DISABLE_IMPLICIT_TOKEN=1 está configurado	Passe O parâmetro explicitamente, ou desconfigue-o
Token de leitura rejeitado por uma organização	A política da organização permite apenas tokens refinados	Crie um token refinado escopo para essa organização

Se um token vazar

Delete ou atualize-o na aba Access Tokens. Se você encontrar o token de outra pessoa — em um repositório público, um Space, um log — você pode invalidá-lo sem possuir a conta, via POST https://huggingface.co/api/credentials/revoke com um corpo JSON de {"credentials": ["hf_..."]}. Tokens correspondentes morrem imediatamente e o proprietário recebe um e-mail. O endpoint sempre retorna 202 Accepted independentemente de o token existir ou não, portanto não pode ser abusado para testar se um token está ativo. Para CI, a resposta mais limpa é não armazenar um token de longa duração: Trusted Publishers troca a identidade OIDC do seu provedor CI por um token Hub de curta duração por execução.

Perguntas frequentes

Um token do Hugging Face é gratuito?

Sim. Criar tokens não custa nada em qualquer nível de conta, e não há um limite documentado para quantos você pode ter. Os custos só aparecem quando um token é usado contra computação paga — Inference Providers além dos seus créditos mensais, Inference Endpoints, hardware de Spaces atualizado ou Jobs.

Os tokens do Hugging Face expiram?

Tokens que você cria manualmente em settings não carregam expiração — duram até você deletar ou atualizá-los. Tokens criados pelo fluxo de dispositivo do navegador durante hf auth login são a exceção: expiram, mas atualizam automaticamente enquanto você continua usando-os.

Qual é a diferença entre read, write e fine-grained?

leem pode baixar qualquer coisa que você já possa ver, incluindo repositórios privados. write adiciona acesso de push. fine-grained começa do zero e concede apenas o que você marca, razão pela qual Hugging Face recomenda para produção e por que algumas organizações rejeitam tokens read/write completamente com um 403.

Posso usar um token em várias máquinas?

Tecnicamente sim, mas a melhor prática documentada é um token por máquina ou app — laptop, notebook Colab, servidor de inferência. Rotacionar um token compartilhado quebra todos os consumidores de uma vez; rotacionar um token por máquina quebra apenas um.

Preciso de um token para executar modelos localmente?

Only for gated or private weights. Public ungated models download anonymously, and Ollama’s registry needs no credentials — see the Guia de instalação do Ollama. Se local faz sentido versus uma API é geralmente uma questão de economia; o calculadora de self-hosting vs API coloca um número de break-even nela.

Onde coloco o token no Google Colab?

Use o painel de segredos do Colab (o ícone de chave) para armazená-lo como HF_TOKEN em vez de hardcodificá-lo em uma célula, depois ative acesso ao notebook. Notebooks são commitados e compartilhados muito mais casualmente que arquivos de código-fonte, e um token colado em uma célula viaja com a cópia.

Fontes

• Hugging Face Hub — Tokens de acesso do usuário (funções, melhores práticas, revogação de token vazado, políticas de token organizacional)
• huggingface_hub — Variáveis de ambiente (HF_TOKEN, HF_TOKEN_PATH, HF_HOME padrões)
• huggingface_hub — Referência de CLI (hf auth subcomandos e sinalizadores)
• Inference Providers — Preços e faturamento (créditos mensais, X-HF-Bill-To)
• Hugging Face Hub — Modelos com acesso restrito (solicitações de acesso, fluxo de aprovação apenas no navegador)

Os preços dos modelos e valores de VRAM são do Convly models database. Compare a capacidade em relação ao custo em Ranking de LLMs.