Access gated models (Llama, FLUX) and fix 401 errors

Models like Llama and FLUX are gated: you must accept their licence and authenticate before any download works. Miss either step and every request returns a 401 or 403.

1. Accept the licence on the model page

Log in at huggingface.co, open the model, and click Agree and send request to access repo (some repos label it Acknowledge license). If approval is automatic you get access immediately; if the author reviews manually, you wait. Access is granted per user, never to a whole organization. The flow is described in the official gated-models guide.

2. Create a read or fine-grained token

Go to Settings, then Access Tokens, then New token. A read token downloads any repo you can read, including gated ones you have been granted. For production prefer a fine-grained token scoped to only the models you need. Token roles are explained in the security-tokens docs. Never print a token to logs or commit it.

hf auth login

Paste the token when prompted; it is stored under HF_HOME. Confirm which account it belongs to:

hf auth whoami

Prints your username. This must be the account that holds the licence approval.

4. Set HF_TOKEN for scripts and CI

macOS / Linux:

export HF_TOKEN=hf_xxx

Windows (PowerShell):

$env:HF_TOKEN = "hf_xxx"

HF_TOKEN overrides the stored login for that process, which is how you authenticate in CI without running hf auth login. In GitHub Actions put it in a repository secret, not the workflow file.

5. Use the token in Python

from huggingface_hub import login
login()  # reads HF_TOKEN, or prompts if unset

Logs the whole process in. Or authenticate one call only:

from huggingface_hub import hf_hub_download
hf_hub_download("meta-llama/Llama-3.1-8B-Instruct", "config.json", token="hf_xxx")

The token= argument works the same way on from_pretrained in transformers and diffusers.

6. Fix 401 and 403 errors

401 Unauthorized / “Repository Not Found” — no token, or a bad one. The Hub hides gated repos from anonymous callers, so a missing token looks like a missing repo. Run hf auth login or set HF_TOKEN, then hf auth whoami to confirm.
403 with GatedRepoError — you are authenticated, but “Access to model … is restricted and you are not in the authorized list.” You have not accepted the licence, or manual approval is still pending. Open the model page, agree, and wait if approval is manual.
403 with header x-error-code: GatedRepo on a valid read token — the token’s account is not the approved one. Log in with the same account that accepted the licence.

Verify it worked

hf download meta-llama/Llama-3.1-8B-Instruct config.json

Prints a local file path with no 401 or 403. Auth and licence are both in place.

Next: download models with the hf CLI · generate images with FLUX locally.