How to sign in to the Hugging Face Hub from Python.

The Hugging Face Hub is where the machine learning world stores its models — and sooner or later every practitioner needs to do more than anonymously download from it: pull a gated or private model, or push a fine-tuned model of their own. Both require authentication. This guide covers the whole flow: creating a token, logging in from scripts, notebooks, and CI, and the actual push/pull commands.

Step 1: create an access token

Authentication on the Hub is token-based. With a (free) Hugging Face account, go to Settings → Access Tokens and create one. You'll choose a token type:

• Read — download models and datasets, including private and gated ones you have access to. Enough for most consumption use.
• Write — everything read can do, plus creating repos and uploading files. Needed to push models.
• Fine-grained — scoped permissions per repo or organization. The right choice for shared machines and CI, because a leaked token can only touch what you scoped it to.

The token is shown once, starts with hf_, and should be treated like a password: don't paste it into code, don't commit it, and rotate it if it ever appears in a log.

Step 2: install the client library

pip install huggingface_hub

If you use transformers, datasets, or diffusers, you already have it — they all depend on huggingface_hub and share its authentication automatically. Log in once and the whole ecosystem is signed in.

Step 3: log in

There are four ways to authenticate, in rough order of how often you'll want each:

From the terminal (interactive machines)

hf auth login

(On older installs the equivalent command is huggingface-cli login.) Paste your token at the prompt. It's stored in your Hugging Face home directory (by default ~/.cache/huggingface/token), and every subsequent Python session on that machine is authenticated — nothing to add to your code at all. Verify with:

hf auth whoami

From Python

from huggingface_hub import login

# Interactive: prompts for the token and stores it
login()

# Non-interactive: pass the token explicitly (e.g. read from a secrets manager)
login(token=my_token)

From a notebook (Jupyter / Colab)

from huggingface_hub import notebook_login

notebook_login()  # renders a login widget in the notebook

In Google Colab there's an even nicer route: store the token once under the key HF_TOKEN in Colab's Secrets panel (the key icon in the sidebar), grant the notebook access, and the library picks it up automatically.

From an environment variable (CI, servers, containers)

export HF_TOKEN="hf_..."

The library reads HF_TOKEN automatically — no login call needed. This is the right pattern for GitHub Actions (set it as a repository secret), Docker containers (pass it with -e HF_TOKEN), and any headless environment. An explicitly passed token= argument takes precedence over the environment variable, which in turn takes precedence over the token stored by login.

Whichever route you used, confirm it worked:

from huggingface_hub import whoami

print(whoami()["name"])  # your username

Pushing a model to the Hub

With a write-capable token, uploading a transformers model is one method call. This is the typical end-of-fine-tuning sequence:

from transformers import AutoModelForSequenceClassification, AutoTokenizer

model = AutoModelForSequenceClassification.from_pretrained("./my-finetuned-model")
tokenizer = AutoTokenizer.from_pretrained("./my-finetuned-model")

# Creates the repo if it doesn't exist, then uploads
model.push_to_hub("your-username/my-model")
tokenizer.push_to_hub("your-username/my-model")

# Private repo instead:
model.push_to_hub("your-username/my-model", private=True)

For arbitrary files — custom architectures, checkpoints, anything that isn't a standard transformers model — use the lower-level API:

from huggingface_hub import HfApi

api = HfApi()
api.create_repo("your-username/my-model", exist_ok=True, private=True)
api.upload_folder(
    folder_path="./my-finetuned-model",
    repo_id="your-username/my-model",
)

Every repo on the Hub is a Git repository under the hood, so uploads are versioned: each push creates a commit, and you can pin, diff, and roll back. Add a model card (README.md) with training details and intended use — it's the first thing users of your model (including future you) will look for.

Pulling models from the Hub

Downloading is the mirror image. For transformers models:

from transformers import AutoModelForSequenceClassification, AutoTokenizer

# Works for public, private, and gated repos — auth is picked up automatically
model = AutoModelForSequenceClassification.from_pretrained("your-username/my-model")
tokenizer = AutoTokenizer.from_pretrained("your-username/my-model")

# Pin an exact version for reproducibility (any git revision works)
model = AutoModelForSequenceClassification.from_pretrained(
    "your-username/my-model", revision="v1.0"
)

For single files or full snapshots without the transformers machinery:

from huggingface_hub import hf_hub_download, snapshot_download

config_path = hf_hub_download(repo_id="your-username/my-model", filename="config.json")
local_dir = snapshot_download(repo_id="your-username/my-model")

Downloads land in a local cache (~/.cache/huggingface/hub by default), so repeated from_pretrained calls don't re-download. On disk-constrained machines, point the cache elsewhere by setting the HF_HOME environment variable.

Common problems

• 401 Unauthorized on a public model — usually a gated repo (Llama, Gemma, and friends): you must accept the license on the model's page with your account first, and then be authenticated when downloading.
• 403 Forbidden when pushing — your token is read-only, or a fine-grained token doesn't include that repo. Check the token's scope.
• Works locally, fails in CI — the login stored by hf auth login lives on your machine, not in the runner. Set HF_TOKEN as a secret in the CI environment.
• Token committed to Git — revoke it immediately in your token settings and create a new one. Hugging Face also scans public repos for leaked tokens and will invalidate ones it finds, but don't rely on that.

All posts