Hugging Face Token: come crearlo, archiviarlo e utilizzarlo

Un token Hugging Face è un User Access Token che autentica la tua macchina, script o job CI su Hugging Face Hub. Lo crei nelle impostazioni del tuo account sotto la scheda Access Tokens , scegli un ruolo (leggere, write o fine-grained), poi esegui hf auth login e incollalo oppure imposta HF_TOKEN nel tuo ambiente. I token assomigliano a hf_....

Cosa autorizza effettivamente il token

Tre cose, in pratica: scaricare file da repository privati o limitati, fare push di file su repository in cui puoi scrivere, e chiamare Provider di inferenza come token bearer. I pesi dei modelli pubblici non hanno bisogno di token — hf download gpt2 config.json funziona senza autenticazione.

La documentazione di Hugging Face descrive il token come utilizzabile «al posto di una password» per git e autenticazione di base, il che è il modello mentale corretto: è una credenziale, non una API key legata a un singolo prodotto.

I tre tipi di token

Ruolo	Concede	Usalo per
leggere	Accesso in lettura a ogni repo che puoi già leggere, inclusi i repo privati che tu o le tue organizzazioni possiedi	Scaricare pesi limitati, eseguire inferenza, notebook
write	Tutto leggere fa, più accesso in scrittura ai repo in cui puoi scrivere	Fare push di checkpoint, modificare schede modello, esecuzioni di training che caricano
fine-grained	Solo le risorse specifiche e i permessi che selezioni	App di produzione, CI, qualsiasi cosa condivisa con un team

Hugging Face raccomanda esplicitamente i token a grana fine per l'uso in produzione, sulla base che il raggio di esplosione se uno viene esposto è più piccolo e può essere condiviso all'interno di un'organizzazione senza esporre l'intero account. Un pattern di produzione tipico: un membro dell'organizzazione richiede accesso a un modello protetto, poi crea un token a grana fine con accesso in lettura a quel repository solamente.

Creare un token, passo dopo passo

1. Accedi, fai clic sul tuo avatar (in alto a destra) → Settings.
2. Aprire il file Access Tokens tab — URL diretto huggingface.co/settings/tokens.
3. Fai clic New token.
4. Chiamalo in base alla macchina o all'app che lo conterrà (laptop-read, ci-push), non in base a te stesso. Un token per utilizzo è la best practice documentata, così puoi revocare uno senza rompere il resto.
5. Scegli il ruolo. Per token a grana fine, seleziona i singoli permessi.
6. Copia il valore immediatamente. Successivamente potrai solo eliminarlo o rigenerarlo dalla stessa pagina via Manage.

Se sei in un'organizzazione Team o Enterprise con una policy sui token, un token a grana fine limitato a quell'organizzazione può finire in uno stato Pending finché un admin non lo approva — l'elenco dei token mostra una clessidra arancione accanto, e le chiamate alle risorse dell'organizzazione restituiscono 403 fino all'approvazione.

Accedere dal terminale

La CLI fornita con huggingface_hub si chiama hf. Installa e accedi:

pip install huggingface_hub
hf auth login

Per impostazione predefinita, questo ora esegue un flusso di dispositivo tramite browser: stampa un URL (https://huggingface.co/oauth/device) e un codice breve come ABCD-EFGH. Approvalo nel browser e la CLI salva un token denominato oauth- che si aggiorna automaticamente finché continui a usarlo. Scegliendo Paste an access token invece puoi fornire un token che hai creato manualmente.

Nota sulla denominazione: i tutorial più vecchi usano huggingface-cli login. Il set di comandi è stato riorganizzato sotto hf auth ..., e quale ortografia la tua macchina accetta dipende dalla huggingface_hub versione installata — esegui hf --help per vedere cosa hai effettivamente.

Comando	Funzionalità
hf auth login --token $HF_TOKEN	Accesso non interattivo, sicuro per gli script
hf auth login --token $HF_TOKEN --add-to-git-credential	Scrive anche il token nel tuo git credential helper
hf auth login --force	Accedi di nuovo anche se già autenticato
hf auth whoami	Stampa il tuo username e le organizzazioni; genera errore se non sei collegato
hf auth list	Elenca i nomi dei token archiviati sulla macchina
hf auth switch --token-name NAME	Passa al token attivo
hf auth token	Stampa il token attivo su stdout
hf auth logout --token-name NAME	Elimina un token archiviato (ometti il flag per eliminare tutti)
hf env	Scarica il percorso del token, se un token è salvato, e i git helper configurati

Passa il token tramite $HF_TOKEN piuttosto che digitare la stringa letterale — la documentazione sconsiglia di incollare token grezzi nelle righe di comando dove la cronologia della shell e i log CI possono catturarli.

Dove viene memorizzato il token

Più token denominati vivono in un file stored_tokens ; quello attualmente attivo viene rispecchiato su uno semplice token file. Entrambi si trovano sotto HF_HOME, il cui valore predefinito è ~/.cache/huggingface.

Linux

~/.cache/huggingface/token e ~/.cache/huggingface/stored_tokens. Se XDG_CACHE_HOME è impostata e HF_HOME non lo è, la base diventa $XDG_CACHE_HOME/huggingface invece.

macOS

Come su Linux: ~/.cache/huggingface/token. Hugging Face non utilizza ~/Library/Caches qui, quindi non cercare lì.

Windows

Il percorso si risolve dalla tua directory home: C:Users<you>.cachehuggingfacetoken. Due particolarità specifiche di Windows che vale la pena conoscere. Per prima cosa, la cache dei modelli utilizza i symlink, che richiedono la modalità sviluppatore o una shell di amministrazione; senza di loro riceverai un avviso e file duplicati sul disco, disattivabili con HF_HUB_DISABLE_SYMLINKS_WARNING=1. In secondo luogo, se punti HF_HUB_CACHE a un NAS condiviso con macchine Linux, imposta HF_HUB_DISABLE_SYMLINKS=1 — i symlink scritti su Linux non sono affidabilmente attraversabili su Windows.

Le variabili d'ambiente che contano

Variabile	Effetto	Predefinito
HF_TOKEN	Fornisce il token; sostituisce il token archiviato su disco	non impostata
HF_TOKEN_PATH	Da dove il file del token viene letto e scritto	$HF_HOME/token
HF_HOME	Cartella base per token più cache	~/.cache/huggingface
HF_HUB_DISABLE_IMPLICIT_TOKEN	Impedisce l'allegazione del token alle richieste di lettura che non ne hanno bisogno; viene inviato solo per le chiamate di scrittura	disattivato
HUGGING_FACE_HUB_TOKEN	Alias deprecato — funziona ancora, ma non ha più la precedenza su HF_TOKEN	—

Due insidie. Queste variabili vengono lette al momento dell' import di huggingface_hub, quindi impostarne una dopo l'import non ha effetto — riavvia il kernel. E hf auth logout non può disconnetterti da un token fornito tramite HF_TOKEN; devi annullare l'impostazione della variabile.

Usare il token con git

La clonazione di repository di grandi dimensioni su HTTPS richiede una password — fornisci il token, non la password del tuo account:

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

Per evitare di riscrivere, accedi con --add-to-git-credential, che passa il token al tuo helper configurato (store su Linux, Keychain su macOS, Windows Credential Manager su Windows). Conferma cosa è collegato con hf env, che stampa una riga Configured git credential helpers .

Usare il token per l'inferenza ospitata

Lo stesso token è la credenziale bearer per i provider di inferenza, che espone un endpoint compatibile con OpenAI su 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"}]}'

Per questo percorso un token a granularità fine con il permesso Effettua chiamate ai provider di inferenza è la soluzione più appropriata. Sulla fatturazione, Hugging Face pubblica crediti mensili di $0,10 per account gratuiti, $2,00 per PRO e $2,00 per membro per organizzazioni Team ed Enterprise, quindi pagamento a consumo alle tariffe del provider senza ricarico HF. Le organizzazioni Team ed Enterprise possono centralizzare la fatturazione inviando X-HF-Bill-To: my-org-name come intestazione mentre ogni membro mantiene il proprio token.

Questi crediti si esauriscono rapidamente alle tariffe dei modelli di frontiera — un modello prezzato come Claude Opus 5 a $5,00 in / $25,00 out per 1M token brucia $2,00 su circa 80k token in output. I modelli open-weights sono un ordine di grandezza diverso: Llama 3.3 70B costa $0,10 in / $0,32 out per 1M token, e Llama 3.1 8B $0,02 in / $0,03 out. Modella il Calcolatore costi API rispetto al tuo volume di token prima di collegare un token a qualsiasi cosa che si ripete.

Modelli limitati: il token è necessario ma non sufficiente

Per i repository gated — la maggior parte delle release Llama e Gemma — un token valido trasporta solo l'accesso che ti è già stato concesso. Per la documentazione dei modelli gated di Hugging Face, la richiesta di accesso stessa «può essere eseguita solo dal tuo browser»: apri la pagina del modello mentre sei loggato, completa il modulo, fai clic su Agree. L'approvazione è automatica o manuale, e gli autori possono revocarlo in seguito senza preavviso. Solo allora hf auth login sblocca il download in uno script. Tipicamente vedrai un 401 quando nessun token è inviato e un 403 quando il token è valido ma il tuo account manca di accesso.

Quando non hai bisogno di un token affatto

I pesi pubblici ungated si scaricano senza credenziali, quindi uno stack puramente locale spesso non ha bisogno di token. Ollama tira dal suo registro interamente, e llama.cpp o LM Studio possono recuperare GGUF pubblici anonimamente. Ciò che decide la tua configurazione è la memoria, non l'autenticazione: Llama 3.1 8B ha bisogno di circa 5 GB di VRAM a 4-bit e Llama 3.3 70B di circa 40 GB, mentre DeepSeek R1 vuole circa 400 GB e Kimi K3 circa 1,4 TB — territorio di cluster. Confronta il tuo rispetto al Calcolatore VRAM o il tabella dei requisiti di VRAM per modello.

Risoluzione dei problemi

Sintomo	Causa probabile	Soluzione
401 Unauthorized	Nessun token inviato, o è stato eliminato sul server	hf auth whoami; esegui di nuovo hf auth login --force
403 su un repository gated	Il token va bene; l'account manca di accesso	Richiedi accesso nel browser sulla pagina del modello
403 con «revocato dall'amministratore dell'organizzazione»	L'organizzazione aziendale ha revocato il token — permanente	Eliminalo e creane uno nuovo
Funziona in shell, fallisce nel notebook	HF_TOKEN impostato dopo l'importazione, o un ambiente kernel diverso	Riavvia il kernel; verifica con hf env
I tuoi modelli privati mancano da un elenco	HF_HUB_DISABLE_IMPLICIT_TOKEN=1 è impostato	Passa il flag esplicitamente, o annullalo
Token di lettura rifiutato da un'organizzazione	La politica dell'organizzazione consente solo token con granularità fine	Crea un token con granularità fine limitato a quell'organizzazione

Se un token trapela

Eliminalo o aggiornalo dalla scheda Access Tokens. Se trovi il token di qualcun altro — in un repository pubblico, uno Space, un log — puoi invalidarlo senza possedere l'account, tramite POST https://huggingface.co/api/credentials/revoke con un corpo JSON di {"credentials": ["hf_..."]}. I token corrispondenti muoiono immediatamente e il proprietario riceve un'email. L'endpoint restituisce sempre 202 Accepted indipendentemente dal fatto che il token esistesse o meno, quindi non può essere sfruttato per verificare se un token è attivo. Per CI, la risposta più pulita è non archiviare affatto un token a lunga durata: Trusted Publishers scambia l'identità OIDC del tuo provider CI con un token Hub di breve durata per esecuzione.

Domande frequenti

Un token Hugging Face è gratuito?

Sì. Creare token non costa nulla su nessun livello di account e non esiste un limite documentato su quanti se ne possono possedere. I costi si presentano solo quando un token viene utilizzato per il calcolo a pagamento — Inference Providers oltre i tuoi crediti mensili, Inference Endpoints, hardware Spaces aggiornato o Jobs.

I token Hugging Face scadono?

I token che crei manualmente nelle impostazioni non hanno scadenza — durano finché non li elimini o aggiorni. I token creati dal flusso del dispositivo browser durante hf auth login sono l'eccezione: scadono, ma si aggiornano automaticamente mentre continui a usarli.

Qual è la differenza tra read, write e fine-grained?

leggere può scaricare qualsiasi cosa tu possa già vedere, compresi i repository privati. write aggiunge l'accesso push. fine-grained inizia da nulla e concede solo ciò che selezioni, ecco perché Hugging Face lo consiglia per la produzione e perché alcune organizzazioni rifiutano completamente i token read/write con un 403.

Posso usare un token su più macchine?

Tecnicamente sì, ma la best practice documentata è un token per macchina o app — laptop, notebook Colab, server di inferenza. Ruotare un token condiviso interrompe ogni consumer contemporaneamente; ruotare un token per macchina interrompe uno solo.

Ho bisogno di un token per eseguire modelli localmente?

Only for gated or private weights. Public ungated models download anonymously, and Ollama’s registry needs no credentials — see the Guida all'installazione di Ollama. Se il locale ha senso rispetto a un'API è solitamente una questione economica; il calcolatore self-hosting vs API fornisce un numero di pareggio su di esso.

Dove metto il token in Google Colab?

Usa il pannello dei segreti di Colab (l'icona chiave) per memorizzarlo come HF_TOKEN piuttosto che codificarlo in una cella, quindi abilita l'accesso al notebook. I notebook vengono committati e condivisi molto più casualmente dei file sorgente, e un token incollato in una cella viaggia con la copia.

Fonti

• Hugging Face Hub — Token di accesso utente (ruoli, best practices, revoca di un token compromesso, politiche dei token dell'organizzazione)
• huggingface_hub — Variabili di ambiente (HF_TOKEN, HF_TOKEN_PATH, HF_HOME impostazioni predefinite)
• huggingface_hub — Riferimento CLI (hf auth sottocomandi e flag)
• Inference Providers — Prezzi e fatturazione (crediti mensili, X-HF-Bill-To)
• Hugging Face Hub — Modelli controllati (richieste di accesso, flusso di approvazione solo browser)

I prezzi dei modelli e i dati VRAM provengono da database dei modelli Convly. Confronta le capacità rispetto al costo su Classifica LLM.