20 min

Account, Token und die CLI

Die CLI heißt seit Juli 2025 hf, und ein Token mit Schreibrechten braucht fast niemand.

Meilenstein hf auth whoami nennt deinen Benutzernamen, ein kleines Modell liegt im Cache, und du kannst sagen, in welchem Verzeichnis es liegt und wie groß es ist.

Ab hier brauchst du ein Konto. Es kostet nichts, und für alles in diesem Kurs reicht die kostenlose Stufe.

Dieses Kapitel hat drei Ergebnisse: einen Account, ein Token mit genau den Rechten, die du brauchst, und eine funktionierende Kommandozeile - die anders heißt, als in fast jeder Anleitung steht, die älter als ein Jahr ist.

Schritt 1 - Account anlegen

Auf huggingface.co/joinExtern - Öffnet in neuem Tab registrieren, E-Mail bestätigen, fertig. Der Benutzername ist gleichzeitig dein Namensraum: Alles, was du später veröffentlichst, heißt deinname/irgendwas. Er lässt sich später ändern, aber dann brechen Links - such dir gleich einen aus, den du behalten willst.

Schritt 2 - Die Bibliothek installieren

bash
python -m venv .venv && source .venv/bin/activate
pip install -U huggingface_hub

Auf Windows heißt die zweite Hälfte der ersten Zeile .venv\\Scripts\\activate.

Das Paket bringt zwei Dinge mit: den Python-Client (HfApi, snapshot_download und Verwandte) und das Kommandozeilenwerkzeug.

Schritt 3 - Die CLI heißt hf

Prüf, dass es da ist:

bash
hf version
hf --help

Die Aufrufe, die du in diesem Kurs brauchst, folgen alle demselben Muster:

BefehlWozu
hf auth loginToken hinterlegen
hf auth whoamiwer bin ich gerade
hf download <repo>Repo in den Cache holen
hf upload <repo> <ordner>Dateien hochladen
hf repo create <name>neues Repo anlegen

Schritt 4 - Ein Token, das möglichst wenig darf

Tokens legst du unter huggingface.co/settings/tokensExtern - Öffnet in neuem Tab an. Es gibt drei Sorten, und die Reihenfolge im Formular verführt zur falschen Wahl:

  • read - darf alles lesen, was dir zugänglich ist, inklusive privater Repos.
  • write - darf zusätzlich schreiben, überall, in jedem deiner Repos.
  • fine-grained - darf genau das, was du ankreuzt, und nur in den Repos oder Organisationen, die du auswählst.

Nimm fine-grained. Das ist auch die offizielle Empfehlung für den produktiven Einsatz, und der Grund ist unspektakulär: Ein Token landet irgendwann versehentlich in einem Log, einem Screenshot oder einem Commit. Was dann passiert, hängt allein davon ab, was das Token darf.

Für dieses Kapitel und die folgenden brauchst du:

  • Read access to contents of all public gated repos (falls du je ein gesperrtes Modell willst)
  • Write access to contents/settings - aber nur für deinen eigenen Namensraum, und ehrlich gesagt erst ab Kapitel 04. Bis dahin genügt Lesen.

Anmelden:

bash
hf auth login
# Token einfügen (die Eingabe bleibt unsichtbar), dann:
hf auth whoami
# → deinbenutzername

Das Token liegt danach in ~/.cache/huggingface/token. In Skripten und CI nimmst du es nicht von dort, sondern aus der Umgebungsvariablen HF_TOKEN - dann steht es nirgends im Code.

Schritt 5 - Der erste Download und wo er landet

bash
hf download Qwen/Qwen2.5-0.5B-Instruct

Rund 1 GB, je nach Leitung eine halbe bis zwei Minuten. Am Ende gibt der Befehl einen Pfad aus, und der sieht ungefähr so aus:

~/.cache/huggingface/hub/models--Qwen--Qwen2.5-0.5B-Instruct/snapshots/<commit-sha>/

Drei Dinge stecken in diesem Pfad:

  1. ~/.cache/huggingface/hub ist der zentrale Cache. Jede Bibliothek und jedes Skript auf deinem Rechner benutzt denselben - ein Modell wird nie zweimal geladen, egal aus welchem Projekt heraus.
  2. models--Org--Name ist der umkodierte Repo-Name. Die doppelten Bindestriche stehen für die Schrägstriche.
  3. snapshots/<commit-sha> ist der entscheidende Teil: Der Cache ist nach Commits organisiert, nicht nach Versionsnummern. Genau deshalb kannst du in Kapitel 03 auf einen Commit pinnen, ohne dass es dich etwas kostet.

Möchtest du den Cache woanders haben - auf einer größeren Platte, in einem gemeinsamen Verzeichnis auf dem Server -, setz HF_HOME:

bash
export HF_HOME=/daten/huggingface
hf download Qwen/Qwen2.5-0.5B-Instruct

Alles, auch das Token, zieht dann dorthin um. Auf einem Server, auf dem mehrere Dienste dieselben Modelle brauchen, ist das die erste Zeile, die man schreibt.

Nur Teile eines Repos holen geht auch, und bei großen Modellen ist das der Unterschied zwischen 15 GB und 150 GB:

bash
hf download Qwen/Qwen2.5-0.5B-Instruct --include "*.safetensors" "*.json"

Warum das schneller war, als du erwartet hast

Lange Zeit lagen große Dateien auf dem Hub in Git LFS. Seit dem 23. Mai 2025 ist für neue Konten und Organisationen Xet die Voreinstellung - ein anderes Speicher-Backend, das Dateien in inhaltsabhängige Blöcke schneidet und nur die Blöcke überträgt, die sich geändert haben.

Praktisch heißt das: Wenn ein Modellanbieter eine 8-GB-Gewichtsdatei neu hochlädt, weil sich etwas Kleines geändert hat, lädst du beim nächsten Mal nicht noch einmal 8 GB. Du musst dafür nichts tun - pip install -U huggingface_hub bringt das Paket hf_xet mit, und es greift automatisch. Wissen musst du es nur, wenn dir jemand eine Anleitung zeigt, in der git lfs install steht: Das ist der alte Weg, er funktioniert weiterhin, ist aber nicht mehr der schnelle.

Der Meilenstein

Drei Zeilen, drei Nachweise:

bash
hf auth whoami
du -sh ~/.cache/huggingface/hub
ls ~/.cache/huggingface/hub

Der erste Befehl nennt deinen Benutzernamen. Der zweite sagt dir, wie viel Platz der Cache belegt. Der dritte zeigt das Verzeichnis mit dem umkodierten Repo-Namen darin.

Wenn du alle drei Ausgaben erklären kannst - wer du bist, wo die Dateien liegen, wie groß sie sind -, ist das Kapitel erledigt. Genau das ist übrigens auch die Antwort auf die Frage „warum ist meine Systemplatte voll“: Der Cache räumt sich nicht von selbst auf.

Teilen
LinkedInXBlueskyWhatsAppE-Mail