Hugging Face Token: How to Create, Store, and Use It

A Hugging Face token is a User Access Token that authenticates your machine, script or CI job to the Hugging Face Hub. You create one in your account settings under the Access Tokens tab, choose a role (leem, write ou fine-grained), then either run hf auth login and paste it or set HF_TOKEN in your environment. Tokens look like hf_....

What the token actually authorises

Three things, in practice: downloading files from private or gated repositories, pushing files to repositories you can write to, and calling Provedores de Inferência as a bearer token. Public model weights need no token at all — hf download gpt2 config.json works unauthenticated.

Hugging Face’s docs describe the token as usable “in place of a password” for git and basic auth, which is the right mental model: it is a credential, not an API key tied to one product.

The three token types

Função	Grants	Use it for
leem	Read access to every repo you can already read, including private repos you or your orgs own	Downloading gated weights, running inference, notebooks
write	Everything leem does, plus write access to repos you can write to	Pushing checkpoints, editing model cards, training runs that upload
fine-grained	Only the specific resources and permissions you tick	Production apps, CI, anything shared with a team

Hugging Face explicitly recommends fine-grained tokens for production use, on the grounds that the blast radius if one leaks is smaller and it can be shared inside an organisation without exposing your whole account. A typical production pattern: one org member requests access to a gated model, then mints a fine-grained token with read access to that repo only.

Creating a token, step by step

1. Sign in, click your avatar (top right) → Settings.
2. Abra o arquivo Access Tokens tab — direct URL huggingface.co/settings/tokens.
3. Clique New token.
4. Name it after the machine or app that will hold it (laptop-read, ci-push), not after yourself. One token per usage is the documented best practice, so you can revoke one without breaking the rest.
5. Pick the role. For fine-grained, tick the individual permissions.
6. Copy the value immediately. Later you can only delete or refresh it from the same page via Manage.

If you are on a Team or Enterprise org with a token policy, a fine-grained token scoped to that org may land in a Pending state until an admin approves it — the token list shows an orange hourglass next to it, and calls against org resources return 403 until approval.

Logging in from the terminal

The CLI shipped with huggingface_hub is called hf. Install and log in:

pip install huggingface_hub
hf auth login

By default this now runs a browser device flow: it prints a URL (https://huggingface.co/oauth/device) and a short code such as ABCD-EFGH. Approve it in the browser and the CLI saves a token named oauth-<username> that refreshes itself as long as you keep using it. Choosing Paste an access token instead lets you supply a token you made by hand.

Note on naming: older tutorials use huggingface-cli login. The command set has been reorganised under hf auth ..., and which spelling your machine accepts depends on the huggingface_hub version installed — run hf --help to see what you actually have.

Comando	O que faz
hf auth login --token $HF_TOKEN	Non-interactive login, safe for scripts
hf auth login --token $HF_TOKEN --add-to-git-credential	Also writes the token to your git credential helper
hf auth login --force	Re-login even if already authenticated
hf auth whoami	Prints your username and orgs; errors if not logged in
hf auth list	Lists the token names stored on the machine
hf auth switch --token-name NAME	Switches the active token
hf auth token	Prints the active token to stdout
hf auth logout --token-name NAME	Deletes one stored token (omit the flag to delete all)
hf env	Dumps token path, whether a token is saved, and configured git helpers

Pass the token via $HF_TOKEN rather than typing the literal string — the docs warn against pasting raw tokens into command lines where shell history and CI logs can capture them.

Where the token is stored

Multiple named tokens live in a stored_tokens file; the currently active one is mirrored to a plain token file. Both sit under HF_HOME, which defaults to ~/.cache/huggingface.

Linux

~/.cache/huggingface/token e ~/.cache/huggingface/stored_tokens. If XDG_CACHE_HOME is set and HF_HOME is not, the base becomes $XDG_CACHE_HOME/huggingface instead.

macOS

Same as Linux: ~/.cache/huggingface/token. Hugging Face does not use ~/Library/Caches here, so don’t go looking there.

Windows

The path resolves from your home directory: C:Users<you>.cachehuggingfacetoken. Two Windows-specific quirks worth knowing. First, the model cache uses symlinks, which require Developer Mode or an admin shell; without them you get a warning and duplicated files on disk, silenceable with HF_HUB_DISABLE_SYMLINKS_WARNING=1. Second, if you point HF_HUB_CACHE at a NAS shared with Linux boxes, set HF_HUB_DISABLE_SYMLINKS=1 — symlinks written on Linux are not reliably traversable on Windows.

The environment variables that matter

Variable	Effect	Padrão
HF_TOKEN	Supplies the token; overrides the token stored on disk	não definida
HF_TOKEN_PATH	Where the token file is read from and written to	$HF_HOME/token
HF_HOME	Base folder for token plus cache	~/.cache/huggingface
HF_HUB_DISABLE_IMPLICIT_TOKEN	Stops the token being attached to read requests that don’t need it; it is then sent only for write calls	desativado
HUGGING_FACE_HUB_TOKEN	Deprecated alias — still works, but no longer takes precedence over HF_TOKEN	—

Two gotchas. These variables are read at import time of huggingface_hub, so setting one after the import has no effect — restart the kernel. And hf auth logout cannot log you out of a token supplied via HF_TOKEN; you have to unset the variable.

Using the token with git

Cloning large repos over HTTPS prompts for a password — supply the token, not your account password:

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

To avoid retyping, log in with --add-to-git-credential, which hands the token to your configured helper (store on Linux, Keychain on macOS, Windows Credential Manager on Windows). Confirm what’s wired up with hf env, which prints a Configured git credential helpers line.

Using the token for hosted inference

The same token is the bearer credential for Inference Providers, which exposes an OpenAI-compatible endpoint at 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"}]}'

For this path a fine-grained token with the Efetuar chamadas aos Provedores de Inferência permission is the tightest fit. On billing, Hugging Face publishes monthly credits of $0.10 for free accounts, $2.00 for PRO, and $2.00 per seat for Team and Enterprise orgs, then pay-as-you-go at the provider’s own rates with no HF markup. Team and Enterprise orgs can centralise billing by sending X-HF-Bill-To: my-org-name as a header while each member keeps their own token.

Those credits go fast at frontier-model rates — a model priced like Claude Opus 5 at $5.00 in / $25.00 out per 1M tokens burns $2.00 in roughly 80k output tokens. Open-weights models are a different order of magnitude: Llama 3.3 70B runs $0.10 in / $0.32 out per 1M tokens, and Llama 3.1 8B $0.02 in / $0.03 out. Model our Calculadora de custos de API against your token volume before wiring a token into anything that loops.

Gated models: the token is necessary but not sufficient

For gated repos — most Llama and Gemma releases — a valid token only carries the access you have already been granted. Per Hugging Face’s gated models documentation, the access request itself “can only be done from your browser“: open the model page while logged in, complete the form, click Agree. Approval is either automatic or manual, and authors can revoke it later without notice. Only then does hf auth login unlock the download in a script. Typically you’ll see a 401 when no token is sent and a 403 when the token is valid but your account lacks access.

When you don’t need a token at all

Ungated public weights download without credentials, so a purely local stack often needs no token. Ollama pulls from its own registry entirely, and llama.cpp or LM Studio can fetch public GGUFs anonymously. What decides your setup is memory, not authentication: Llama 3.1 8B needs about 5 GB of VRAM at 4-bit and Llama 3.3 70B about 40 GB, while DeepSeek R1 wants roughly 400 GB and Kimi K3 around 1.4 TB — cluster territory. Check yours against the Calculadora de VRAM ou o tabela de requisitos de VRAM por modelo.

Solução de problemas

Sintoma	Likely cause	Corrigir
401 Unauthorized	No token sent, or it was deleted server-side	hf auth whoami; re-run hf auth login --force
403 on a gated repo	Token is fine; account lacks access	Request access in the browser on the model page
403 with “revoked by the organization administrator”	Enterprise org revoked the token — permanent	Delete it and create a new one
Works in shell, fails in notebook	HF_TOKEN set after import, or a different kernel environment	Restart the kernel; verify with hf env
Your private models missing from a listing	HF_HUB_DISABLE_IMPLICIT_TOKEN=1 is set	Passe O parâmetro explicitly, or unset it
Read token rejected by an org	Org policy permits fine-grained tokens only	Mint a fine-grained token scoped to that org

If a token leaks

Delete or refresh it from the Access Tokens tab. If you find someone else’s token — in a public repo, a Space, a log — you can invalidate it without owning the account, via POST https://huggingface.co/api/credentials/revoke with a JSON body of {"credentials": ["hf_..."]}. Matching tokens die immediately and the owner is emailed. The endpoint always returns 202 Accepted whether or not the token existed, so it can’t be abused to test whether a token is live. For CI, the cleaner answer is not storing a long-lived token at all: Trusted Publishers exchanges your CI provider’s OIDC identity for a short-lived Hub token per run.

Perguntas frequentes

Is a Hugging Face token free?

Yes. Creating tokens costs nothing on any account tier, and there is no documented cap on how many you hold. Costs only appear when a token is used against paid compute — Inference Providers beyond your monthly credits, Inference Endpoints, upgraded Spaces hardware or Jobs.

Do Hugging Face tokens expire?

Tokens you create by hand in settings do not carry an expiry — they last until you delete or refresh them. Tokens minted by the browser device flow during hf auth login are the exception: they expire, but refresh automatically while you keep using them.

What’s the difference between read, write, and fine-grained?

leem can download anything you can already see, including private repos. write adds push access. fine-grained starts from nothing and grants only what you tick, which is why Hugging Face recommends it for production and why some orgs reject read/write tokens outright with a 403.

Can I use one token on several machines?

Technically yes, but the documented best practice is one token per machine or app — laptop, Colab notebook, inference server. Rotating a shared token breaks every consumer at once; rotating a per-machine token breaks one.

Do I need a token to run models locally?

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. Whether local makes sense versus an API is usually an economics question; the calculadora de autohospedagem versus API puts a break-even number on it.

Where do I put the token in Google Colab?

Use Colab’s secrets panel (the key icon) to store it as HF_TOKEN rather than hardcoding it in a cell, then enable notebook access. Notebooks get committed and shared far more casually than source files, and a token pasted into a cell travels with the copy.

— preços de API publicados via OpenRouter e DeepInfra, junho de 2026.

• Hugging Face Hub — User access tokens (roles, best practices, revoking a leaked token, org token policies)
• huggingface_hub — Environment variables (HF_TOKEN, HF_TOKEN_PATH, HF_HOME defaults)
• huggingface_hub — CLI reference (hf auth subcommands and flags)
• Inference Providers — Pricing and billing (monthly credits, X-HF-Bill-To)
• Hugging Face Hub — Gated models (access requests, browser-only approval flow)

Model prices and VRAM figures are from the base de dados de modelos Convly. Compare capability against cost on the Ranking de LLMs.