Hugging-Face-Token: So erstellen, speichern und verwenden Sie es

Ein Hugging-Face-Token ist ein Benutzerzugriffstoken, das Ihre Maschine, Ihr Skript oder Ihren CI-Job gegenüber dem Hugging Face Hub authentifiziert. Sie erstellen es in Ihren Kontoeinstellungen im Reiter Access Tokens Access Tokensein Dokument, write oder fine-grainedread, write, fine-grained hf auth login hf auth login HF_TOKEN HF_TOKEN=hf_... hf_....

Was das Token tatsächlich berechtigt

Praktisch drei Dinge: das Herunterladen von Dateien aus privaten oder gesperrten Repositories, das Hochladen (Push) von Dateien in Repositories, in die Sie schreiben dürfen, sowie der Aufruf von Inference Providers als Bearer-Token. Öffentliche Modellgewichte benötigen keinerlei Token – hf download gpt2 config.json funktioniert ohne Authentifizierung.

Die Dokumentation von Hugging Face beschreibt das Token als Ersatz für ein Passwort „in place of a password“, sowohl für git als auch für Basic Auth – das ist das richtige mentale Modell: Es handelt sich um eine Zugangsdaten (Credential), nicht um einen API-Schlüssel, der an ein einzelnes Produkt gebunden ist.

Die drei Token-Typen

Rolle	Berechtigungen (Grants)	Verwenden Sie es für
ein Dokument	Lesezugriff auf jedes Repository, das Sie bereits lesen können – inklusive privater Repositories, die Sie oder Ihre Organisation besitzen	Herunterladen gesperrter Gewichte, Ausführen von Inferenz, Notebooks
write	Alles ein Dokument was möglich ist, plus Schreibzugriff auf Repositories, in die Sie schreiben dürfen	Hochladen von Checkpoints, Bearbeiten von Modellkarten, Trainingsläufe mit Upload
fine-grained	Nur die spezifischen Ressourcen und Berechtigungen, die Sie aktivieren	Produktionsanwendungen, CI-Pipelines, alles, was innerhalb eines Teams geteilt wird

Hugging Face empfiehlt ausdrücklich feingranulare Tokens für den Produktionsbetrieb, da der mögliche Schaden bei einem Leak geringer ist und sie innerhalb einer Organisation geteilt werden können, ohne Ihr gesamtes Konto preiszugeben. Ein typisches Muster im Produktionsbetrieb: Ein Organisationsmitglied beantragt Zugriff auf ein geschütztes Modell und erstellt dann einen feingranularen Token mit Lesezugriff ausschließlich für dieses Repository.

Token Schritt für Schritt erstellen

1. Melden Sie sich an, klicken Sie auf Ihr Profilbild (oben rechts) → Einstellungen.
2. Öffnen Sie die Access Tokens -Reiter – direkte URL huggingface.co/settings/tokens.
3. Klicken New token.
4. Benennen Sie ihn nach dem Gerät oder der Anwendung, die ihn verwenden wird (z. B.laptop-read, ci-push) – nicht nach sich selbst. Die dokumentierte Best Practice lautet: Ein Token pro Verwendungszweck, damit Sie einzelne Tokens widerrufen können, ohne die anderen zu beeinträchtigen.
5. Wählen Sie die Rolle aus. Bei feingranularen Tokens aktivieren Sie die einzelnen Berechtigungen manuell.
6. Kopieren Sie den Wert sofort. Später können Sie ihn nur noch über die gleiche Seite löschen oder erneuern – dazu klicken Sie auf Verwalten.

Falls Sie einer Team- oder Enterprise-Organisation angehören, für die eine Token-Richtlinie gilt, kann ein feingranularer Token, der auf diese Organisation beschränkt ist, zunächst den Status Ausstehend haben, bis ein Administrator ihn genehmigt – in der Token-Liste erscheint daneben eine orangefarbene Sanduhr, und Aufrufe an Organisationsressourcen liefern bis zur Genehmigung 403 einen Fehler.

Anmeldung über das Terminal

Die mit huggingface_hub ausgelieferte CLI heißt hf. Installieren und anmelden:

pip install huggingface_hub
hf auth login

Standardmäßig verwendet diese nun einen Browser-basierten Geräte-Flow: Sie gibt eine URL aus (https://huggingface.co/oauth/device) sowie einen kurzen Code wie ABCD-EFGH. Bestätigen Sie den Vorgang im Browser – die CLI speichert dann einen Token mit dem Namen oauth-<username> , der sich automatisch erneuert, solange Sie ihn weiterhin nutzen. Wählen Sie stattdessen die Option Zugriffstoken einfügen , um manuell erstellte Tokens einzugeben.

Hinweis zur Namensgebung: Ältere Tutorials verwenden huggingface-cli login. Der Befehlssatz wurde neu unter hf auth ...organisiert; welche Schreibweise Ihr System akzeptiert, hängt von der installierten huggingface_hub Version ab – führen Sie hf --help aus, um zu sehen, welche Befehle tatsächlich verfügbar sind.

Befehl	Was es tut
hf auth login --token $HF_TOKEN	Nicht-interaktive Anmeldung, sicher für Skripte
hf auth login --token $HF_TOKEN --add-to-git-credential	Schreibt den Token außerdem in Ihren Git-Credential-Helfer
hf auth login --force	Erzwingt eine erneute Anmeldung, auch wenn bereits authentifiziert
hf auth whoami	Gibt Ihren Benutzernamen und Ihre Organisationen aus; meldet einen Fehler, falls nicht angemeldet
hf auth list	Listet die auf dem Rechner gespeicherten Token-Namen auf
hf auth switch --token-name NAME	Wechselt den aktiven Token
hf auth token	Gibt den aktiven Token auf stdout aus
hf auth logout --token-name NAME	Löscht einen gespeicherten Token (ohne Flag werden alle gelöscht)
hf env	Zeigt Pfad zum Token, ob ein Token gespeichert ist und konfigurierte Git-Helfer an

Übergeben Sie den Token über $HF_TOKEN anstatt die wörtliche Zeichenfolge einzugeben – in der Dokumentation wird davor gewarnt, rohe Tokens direkt in Befehlszeilen einzufügen, da diese so in der Shell-Historie und in CI-Logs gespeichert werden können.

Wo das Token gespeichert wird

Mehrere benannte Tokens befinden sich in einer stored_tokens -Datei; das derzeit aktive Token wird zudem in eine einfache token -Datei gespiegelt. Beide Dateien liegen unter HF_HOME, dessen Standardwert ~/.cache/huggingface.

Linux

~/.cache/huggingface/token und ~/.cache/huggingface/stored_tokensist. Falls XDG_CACHE_HOME gesetzt ist und HF_HOME nicht, lautet der Basispfad stattdessen $XDG_CACHE_HOME/huggingface .

macOS

Gleich wie unter Linux: ~/.cache/huggingface/token. Hugging Face nutzt hier nicht ~/Library/Caches – suchen Sie also bitte nicht dort danach.

Windows

Der Pfad wird relativ zum Home-Verzeichnis aufgelöst: C:\Users\\.cache\huggingface\token. Zwei Windows-spezifische Besonderheiten sind erwähnenswert: Erstens verwendet der Modell-Cache symbolische Verknüpfungen (symlinks), für die entweder der Entwicklermodus aktiviert oder eine Administrator-Shell geöffnet sein muss; andernfalls erhalten Sie eine Warnung und es werden doppelte Dateien auf der Festplatte angelegt – diese Warnung lässt sich mit HF_HUB_DISABLE_SYMLINKS_WARNING=1unterdrücken. Zweitens, falls Sie HF_HUB_CACHE auf ein NAS verweisen, das gemeinsam mit Linux-Systemen genutzt wird, setzen Sie bitte HF_HUB_DISABLE_SYMLINKS=1 – symbolische Verknüpfungen, die unter Linux erstellt wurden, sind unter Windows nicht zuverlässig durchlaufbar.

Die relevanten Umgebungsvariablen

Variable	Wirkung	Standard
HF_TOKEN	Stellt das Token bereit; überschreibt das auf der Festplatte gespeicherte Token	nicht gesetzt
HF_TOKEN_PATH	Ort, von dem aus die Token-Datei gelesen und in die sie geschrieben wird	$HF_HOME/token
HF_HOME	Basisordner für Token sowie Cache	~/.cache/huggingface
HF_HUB_DISABLE_IMPLICIT_TOKEN	Verhindert, dass das Token an Leseanfragen angehängt wird, die es nicht benötigen; es wird dann ausschließlich bei Schreibaufrufen übermittelt	aus
HUGGING_FACE_HUB_TOKEN	Veralteter Alias – funktioniert noch, hat aber keine höhere Priorität als HF_TOKEN	—

Zwei Fallstricke: Diese Variablen werden beim Import-Zeitpunkt von huggingface_hubausgewertet, sodass eine nachträgliche Setzung nach dem Import ohne Wirkung bleibt – starten Sie den Kernel neu. Und hf auth logout kann Sie nicht von einem Token abmelden, das über HF_TOKENbereitgestellt wurde; dazu müssen Sie die Variable explizit entfernen.

Verwenden des Tokens mit git

Beim Klonen großer Repositories über HTTPS wird nach einem Passwort gefragt – geben Sie hier das Token ein, nicht Ihr Account-Passwort:

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

Um die Eingabe zu vermeiden, melden Sie sich mit --add-to-git-credentialan, wodurch das Token an Ihren konfigurierten Hilfsdienst übergeben wird (store unter Linux, Keychain unter macOS, Windows Credential Manager unter Windows). Überprüfen Sie, welcher Hilfsdienst konfiguriert ist, mit hf env, das eine Zeile mit der Überschrift Konfigurierte Git-Credential-Hilfsprogramme ausgibt.

Verwenden des Tokens für gehostete Inferenz

Dasselbe Token fungiert als Bearer-Credential für Inference Providers, die einen OpenAI-kompatiblen Endpunkt unter 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"}]}'

Für diesen Zugangsweg ist ein feingranulares Token mit der Berechtigung Aufrufe an Inference Providers durchführen die präziseste Wahl. Bezüglich der Abrechnung stellt Hugging Face monatlich Guthaben zur Verfügung von 0,10 $ für kostenlose Konten, 2,00 $ für PRO-Konten und 2,00 $ pro Nutzerplatz für Team- und Enterprise-Organisationenund zahlen dann nach Verbrauch zu den eigenen Tarifen des Anbieters ohne Aufschlag durch Hugging Face. Team- und Enterprise-Organisationen können die Abrechnung zentralisieren, indem sie X-HF-Bill-To: my-org-name als Header übermitteln, während jeder Mitglied seinen eigenen Token behält.

Diese Credits verbrauchen sich rasch bei Tarifen für Spitzenmodelle – ein Modell mit einem Preis wie Claude Opus 5 zu 5,00 $ pro 1 Mio. Eingabetokens und 25,00 $ pro 1 Mio. Ausgabetokens verbraucht etwa 2,00 $ für rund 80.000 Ausgabetokens. Open-Weights-Modelle liegen in einer völlig anderen Größenordnung: Llama 3.3 70B kostet 0,10 $ pro 1 Mio. Eingabetokens und 0,32 $ pro 1 Mio. Ausgabetokens, und Llama 3.1 8B 0,02 $ pro 1 Mio. Eingabetokens und 0,03 $ pro 1 Mio. Ausgabetokens. Berechnen Sie Ihr API-Kostenrechner Modell anhand Ihres Token-Volumens, bevor Sie einen Token in eine Schleife einbinden.

Gesperrte Modelle: Das Token ist notwendig, aber nicht ausreichend

Bei gesperrten Repositories – darunter die meisten Llama- und Gemma-Versionen – gewährleistet ein gültiger Token lediglich den Zugriff, den Sie bereits erhalten haben. Gemäß der Dokumentation zu gesperrten Modellen von Hugging Facekann die Zugriffsanfrage selbst „ausschließlich über Ihren Browser erfolgen“: Öffnen Sie die Modellseite, während Sie angemeldet sind, füllen Sie das Formular aus und klicken Sie auf Zustimmen. Die Genehmigung erfolgt entweder automatisch oder manuell; Autoren können sie später ohne Vorankündigung widerrufen. Erst danach hf auth login ermöglicht der Token den Download über ein Skript. Typischerweise sehen Sie einen 401 Fehler, wenn kein Token gesendet wird, und einen 403 Fehler, wenn der Token zwar gültig ist, Ihr Konto jedoch keinen Zugriff besitzt.

Wann Sie überhaupt kein Token benötigen

Nicht gesperrte öffentliche Gewichte können ohne Anmeldeinformationen heruntergeladen werden; ein rein lokaler Stack benötigt daher oft keinen Token. Ollama lädt ausschließlich aus seiner eigenen Registry, und llama.cpp oder LM Studio können öffentliche GGUFs anonym abrufen. Was Ihre Setup-Entscheidung bestimmt, ist der Speicherbedarf – nicht die Authentifizierung: Llama 3.1 8B benötigt etwa 5 GB VRAM im 4-Bit-Format, Llama 3.3 70B etwa 40 GB, während DeepSeek R1 rund 400 GB und Kimi K3 ca. 1,4 TB erfordert – also Cluster-Bereich. Prüfen Sie Ihren Bedarf anhand der VRAM-Rechner oder das Tabelle zu den VRAM-Anforderungen pro Modell.

Fehlerbehebung

Symptom	Wahrscheinliche Ursache	Korrigieren
401 Unauthorized	Kein Token gesendet oder es wurde serverseitig gelöscht	hf auth whoami– führen Sie hf auth login --force
403 für ein gesperrtes Repository erneut aus	Token ist in Ordnung; Ihr Konto hat keinen Zugriff	Fordern Sie im Browser auf der Modellseite Zugriff an
403 mit dem Hinweis „vom Organisationsadministrator widerrufen“	Enterprise-Organisation hat den Token widerrufen – dauerhaft	Löschen Sie ihn und erstellen Sie einen neuen
Funktioniert in der Shell, scheitert aber im Notebook	HF_TOKEN wurde nach dem Import festgelegt oder es handelt sich um eine andere Kernel-Umgebung	Starten Sie den Kernel neu; überprüfen Sie dies mit hf env
Ihre privaten Modelle fehlen in einer Auflistung	HF_HUB_DISABLE_IMPLICIT_TOKEN=1 ist gesetzt	Übergeben Sie auf – das Flag explizit oder deaktivieren Sie diese Variable
Lesetoken wird von einer Organisation abgelehnt	Die Richtlinie der Organisation erlaubt ausschließlich feingranulare Tokens	Erstellen Sie ein feingranulares Token, das auf diese Organisation beschränkt ist

Falls ein Token kompromittiert wird

Löschen oder aktualisieren Sie es über die Registerkarte „Access Tokens“. Falls Sie jemand anderes Token – in einem öffentlichen Repository, einem Space oder einem Log – finden, können Sie es unabhängig vom Besitz des Kontos ungültig machen, indem Sie POST https://huggingface.co/api/credentials/revoke mit einem JSON-Body wie {"credentials": ["hf_..."]}aufrufen. Übereinstimmende Tokens werden sofort unwirksam, und der Besitzer erhält eine E-Mail. Der Endpunkt gibt stets 202 Accepted zurück – unabhängig davon, ob der Token existierte oder nicht – sodass er nicht missbraucht werden kann, um zu prüfen, ob ein Token noch aktiv ist. Für CI-Umgebungen ist die sauberere Lösung, gar keinen langfristigen Token zu speichern: Trusted Publishers tauscht die OIDC-Identität Ihres CI-Anbieters gegen einen kurzlebigen Hub-Token pro Ausführung ein.

Häufig gestellte Fragen

Ist ein Hugging-Face-Token kostenlos?

Ja. Die Erstellung von Tokens ist für alle Account-Stufen kostenfrei, und es gibt keine dokumentierte Obergrenze für die Anzahl der gleichzeitig gehaltenen Tokens. Kosten entstehen erst, wenn ein Token für kostenpflichtige Rechenleistung genutzt wird – etwa für Inference Providers über Ihr monatliches Guthaben hinaus, für Inference Endpoints, für aufgerüstete Spaces-Hardware oder für Jobs.

Verfallen Hugging-Face-Tokens?

Manuell in den Einstellungen erstellte Tokens haben keine Ablaufzeit – sie bleiben so lange gültig, bis Sie sie löschen oder aktualisieren. Tokens, die während des hf auth login Browser-Geräte-Flows erstellt werden, bilden die Ausnahme: Sie laufen zwar ab, werden aber automatisch erneuert, solange Sie sie weiterhin nutzen.

Was unterscheidet Lese-, Schreib- und feingranulare Tokens?

ein Dokument Ermöglicht den Download aller Inhalte, die Sie bereits einsehen können – inklusive privater Repositories. write Fügt Push-Zugriff hinzu. fine-grained Beginnt bei Null und gewährt ausschließlich die Rechte, die Sie explizit auswählen – weshalb Hugging Face feingranulare Tokens für Produktionsumgebungen empfiehlt und einige Organisationen Lese-/Schreib-Tokens gänzlich ablehnen mit einer 403.

Kann ich ein Token auf mehreren Maschinen verwenden?

Technisch gesehen ja, doch die dokumentierte Best Practice lautet: ein Token pro Maschine oder Anwendung – Laptop, Colab-Notebook, Inferenzserver. Ein Wechsel eines gemeinsam genutzten Tokens unterbricht sämtliche Verbraucher auf einmal; ein Wechsel eines maschinenspezifischen Tokens betrifft nur diese eine Maschine.

Brauche ich ein Token, um Modelle lokal auszuführen?

Nur für gesperrte oder private Gewichte. Öffentliche, ungesperrte Modelle werden anonym heruntergeladen, und die Ollama-Registrierung erfordert keine Anmeldeinformationen – siehe die Ollama-InstallationsanleitungOb eine lokale Ausführung im Vergleich zur Nutzung einer API sinnvoll ist, hängt meist von wirtschaftlichen Überlegungen ab; der Selbsthosting vs. API-Rechner berechnet hierfür eine Break-even-Grenze.

Wo trage ich das Token in Google Colab ein?

Verwenden Sie das Geheimnisse-Feld (Schlüsselsymbol) in Colab, um das Token als HF_TOKEN zu speichern, anstatt es direkt in einer Zelle festzukodieren, und aktivieren Sie anschließend den Notebook-Zugriff. Notebooks werden weitaus ungezwungener committet und geteilt als Quelldateien, und ein in einer Zelle eingefügtes Token wird bei jeder Kopie mitübertragen.

Quellen

• Hugging Face Hub – Benutzerzugriffstoken (Rollen, bewährte Verfahren, Widerruf eines geleakten Tokens, Richtlinien zu Organisationstokens)
• huggingface_hub – Umgebungsvariablen (HF_TOKEN, HF_TOKEN_PATH, HF_HOME (Standardeinstellungen)
• huggingface_hub – CLI-Referenz (hf auth (Unterbefehle und Flags)
• Inference-Anbieter – Preise und Abrechnung (monatliche Guthaben, X-HF-Bill-To)
• Hugging Face Hub – Gesperrte Modelle (Zugriffsanfragen, Genehmigungsablauf ausschließlich im Browser)

Modellpreise und VRAM-Angaben stammen aus der Convly-Modell-Datenbank. Vergleichen Sie Leistungsfähigkeit und Kosten auf der LLM-Leaderboard.