Hugging Face Login

Downloading gated or private models from the Hugging Face Hub requires an authenticated request. The steps above fix the typical "401 Unauthorized" or "Access to model is restricted" error. The sections below explain how authentication works, how the cache is organized, and how to use tokens safely in scripts and servers.

1. Login to Hugging Face CLI

If you haven't logged in yet, authenticate via the command line:

huggingface-cli login

This will prompt you to enter your Hugging Face token. You can generate a token from your Hugging Face account:

2. Verify Repository Access

Ensure you have the necessary permissions to access the restricted model:

3. Set Up API Token

If you're accessing the model programmatically, configure the token properly:

export HUGGINGFACE_TOKEN=<your_token_here>

Or set it directly in your script:

from huggingface_hub import HfApi

api = HfApi()
api.login(token="<your_token_here>")

4. Retry Model Download

Once authenticated, run the command or script again to access the model.

Note:

If you still encounter issues, double-check that the model owners have granted access. If not, you'll need to wait for their approval.

1. How Authentication Works

How Hub Authentication Works Access token hf_... from settings hf auth login or HF_TOKEN env var Token file ~/.cache/huggingface/token huggingface_hub adds Authorization header Hub API checks repo access Download into local cache

Every call that the huggingface_hub library makes, including those made indirectly by transformers, diffusers, and datasets, looks for a token in a fixed order: an explicit token= argument, then the HF_TOKEN environment variable, then the token file written by the CLI login. If one is found it is sent as a bearer token in the Authorization header. The Hub then checks whether the account that owns the token may read the repository. Public models need no token at all; private repositories need membership; gated repositories, such as FLUX.1-dev and many Llama releases, need the account to have accepted the model's licence on its web page first.

2. Gated Models

Gated Model Access Checklist Accept terms on the model page Token scope read / fine-grained Same account token owner = acceptor Retry download from_pretrained

Most failed downloads of gated models have one of three causes. The licence was never accepted, or approval is still pending for repositories that review requests manually. The token belongs to a different account from the one that accepted the terms, which happens when a machine has an old token cached. Or a fine-grained token was created without permission to read gated public repositories. The Hub's error message usually distinguishes between "unauthorized" (no or invalid token) and "restricted" (valid token, no access).

Debugging is easiest from the command line. Run hf auth whoami to see which account the active token belongs to, then open the model page in a browser while logged in as that account and confirm it shows that access has been granted. If both look right, check whether HF_TOKEN is set in the environment, since it takes precedence over the saved login and is a frequent source of confusion when an old value lingers in a shell profile or a service unit file.

3. Worked Example

pip install -U "huggingface_hub[cli]"
hf auth login                      # older releases: huggingface-cli login
hf auth whoami                     # confirm which account the token belongs to
export HF_TOKEN=hf_xxx             # alternative for CI and servers
hf download black-forest-labs/FLUX.1-dev --include "*.json" --local-dir ./flux
import os
from huggingface_hub import login, whoami, snapshot_download

login(token=os.environ["HF_TOKEN"])          # never hard-code the token
print(whoami()["name"])

path = snapshot_download("black-forest-labs/FLUX.1-dev",
                         allow_patterns=["*.json", "*.safetensors"])
print("cached at", path)

from transformers import AutoTokenizer
tok = AutoTokenizer.from_pretrained("bert-base-uncased")   # public, no token needed

The exact CLI command names have changed across huggingface_hub releases; hf --help lists the ones your installed version supports.

4. The Local Cache

Downloads are stored under ~/.cache/huggingface/hub by default, one folder per repository, with content-addressed blobs and per-revision snapshot folders of symlinks. A second from_pretrained for the same revision reads from disk without contacting the network for the files themselves. Set HF_HOME to move the whole cache, for example onto a larger volume, and HF_HUB_OFFLINE=1 to forbid network access entirely once models are cached. Large diffusion and language models can occupy tens of gigabytes, so hf cache tooling or simply removing old repository folders is part of routine maintenance.

5. Pitfalls and Security