# Hugging Face tutorial: find, check and download open models

> The Hugging Face Hub hosts open models, datasets and demo apps as git repositories. This tutorial finds a model with the Hub's filters and reads its model card and license. Then it requests a gated model, creates an access token and downloads only the files you need with `hf`, the command line tool that replaced `huggingface-cli`.

Mindket editors · Published 2026-11-05 · Updated 2026-11-06 · https://mindket.com/learn/hugging-face/hugging-face-hub

## In short

- Settle whether you may ship a model before you write a line of code around it.
- Give each laptop, notebook and server its own key, so one leak means one revoke.
- Preview a download, then fetch just the config and weights your code reads.
- Leave cached files untouched and clear old ones with the cache commands.

## Before you start

You need a free [Hugging Face account](https://huggingface.co/join), Python 3.10 or later and a terminal. Lesson 2 asks for Python 3.11, the oldest version Transformers is tested on, so a 3.11 environment carries you through the whole course. The account is what opens gated models, access tokens and higher download limits. Everything on the Hub lives in a **repository**, a version-controlled folder with commits and branches, much like a GitHub repo. The `huggingface_hub` library reads and writes those repositories from Python. It also ships `hf`, a **CLI** (command line interface, a program you drive by typing commands). If you only want the CLI, the [installation page](https://huggingface.co/docs/huggingface_hub/installation) also offers a standalone installer for macOS, Linux and Windows.

Old tutorials still say `huggingface-cli login`. Hugging Face [renamed the tool to hf](https://huggingface.co/blog/hf-cli) in July 2025, and the [v1.0 migration guide](https://huggingface.co/docs/huggingface_hub/concepts/migration) lists the old name as removed. Commands now read as a resource, then an action: `hf auth login`, `hf cache ls`. Downloads and uploads stay at the top level as `hf download` and `hf upload`. Old guides may also set `HF_HUB_ENABLE_HF_TRANSFER` for faster downloads. The same release ignores it, because speed now comes from the `hf_xet` package, installed with `huggingface_hub` since version 0.32.0.

A model repository usually holds three kinds of file. A `config.json` describes the model's shape. Tokenizer files describe the **tokenizer**, which cuts text into numbered pieces called tokens, the units a model reads. Weight files hold the **weights**, the learned numbers the model computes with, and they make up nearly all of the download.

On Windows, the download cache relies on symlinks, file entries that point at another file. Turn on developer mode in Windows settings, or run Python as admin. Without either, the cache still works, in what the installation page calls a non-optimized manner.

## Step by step, with screenshots

These six steps need no account. They go from the models list to a gated model, with one screenshot of the site for each.

1. Open [huggingface.co/models](https://huggingface.co/models). Under **Tasks**, click **Text Generation**, then open **Sort** and choose **Most downloads**. The list now holds only text generation models, the most downloaded first.
   ![The Hugging Face models page with the Text Generation task and the Sort: Most downloads button ringed in gold. The list starts with openai-community/gpt2.](https://mindket.com/blog/screens/hugging-face-hub-1-models-page.webp?v=06434f7bd913)
2. Type `gpt2` into the search box at the top. A menu of matching models drops down with `openai-community/gpt2` first. Click it.
   ![The search box at the top of the page, ringed in gold, with gpt2 typed in. The menu under it lists models, and openai-community/gpt2 is highlighted first.](https://mindket.com/blog/screens/hugging-face-hub-2-search-box.webp?v=d28f4af7c2d1)
3. The page that opens is the model card. The tags under the name show its task, the libraries that load it and its license. Find the **License** badge before you build on any model. This one says `mit`.
   ![The openai-community/gpt2 model page. The License: mit badge, among the tags under the model name, is ringed in gold.](https://mindket.com/blog/screens/hugging-face-hub-3-model-card.webp?v=d90ce0cc1b40)
4. Click **Files and versions** (just **Files** in a narrow window), next to **Model card**. This is the repository itself. `config.json` is 665 bytes of settings, and `model.safetensors` holds the weights at 548 MB. Most of the rest is the same model saved again for other tools.
   ![The Files tab of openai-community/gpt2, ringed in gold, above the repository file list. config.json, model.safetensors and pytorch_model.bin are among the files.](https://mindket.com/blog/screens/hugging-face-hub-4-files-tab.webp?v=70a8f6b79682)
5. Go back to **Model card** and click **Use this model**. The menu offers **Transformers** under Libraries, notebooks on Google Colab and Kaggle, and local apps such as vLLM.
   ![The Use this model button on the gpt2 page, ringed in gold, with its menu open: Transformers, Google Colab, Kaggle, vLLM, SGLang and Docker Model Runner.](https://mindket.com/blog/screens/hugging-face-hub-5-use-this-model.webp?v=cb7380141bda)
6. Some models ask for your agreement first. Open [google/gemma-2-2b](https://huggingface.co/google/gemma-2-2b) while signed out. A box says you must accept the conditions to reach the files, with **Log in** and **Sign Up** buttons at its foot.
   ![The google/gemma-2-2b model page. The Access Gemma on Hugging Face box, ringed in gold, says to accept the conditions and has Log in and Sign Up buttons.](https://mindket.com/blog/screens/hugging-face-hub-6-gated-model.webp?v=6d7fe7c0a76e)

*Screenshots of huggingface.co, taken on 6 November 2026.*

## Find a model and read its card

Start on [the models page](https://huggingface.co/models) with a task filter, such as text generation or text classification. The Hub lists more than 2M models, 1.5M datasets and 1.5M **Spaces**, its name for hosted demo apps. A task, then a license, cuts that list down before you read a single page. Lesson 2 hands that same task name to `pipeline()`.

Each model page renders the repository's `README.md` as its **model card**: Markdown text under a block of YAML, plain text written as `key: value` lines. The license badge, the task tag and the filters you just used all come from that block. When two models look alike, compare the blocks first. On a model you own, the **Edit model card** button changes the same block through a form.

The license list mixes software licenses such as `apache-2.0` and `mit` with model licenses such as `llama3.1` and `gemma`, and with non-commercial ones like `cc-by-nc-4.0`. A card can also say `license: other` and point to custom terms. The badge names the license. It can't tell you whether your use fits, so read the terms before a model goes into anything you sell.

Two more filters come from the card: training dataset and base model. A **base model** is the one another model was built from. Builders fine-tune it, which means training it further on new data, or quantize it, storing its numbers with fewer bits so it needs less memory. Filtering on a base model lists every variant made from it. That is how you find a smaller copy of a model you already like.

You can read the metadata without a browser. The library's install check prints a model's tags and its task. In the docs' example run on `gpt2`, the tags include `license:mit` and the task is `text-generation`.

````bash
python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"
````

| Card key | What it holds | What it changes for you |
| --- | --- | --- |
| `license` | The license id, shown as a badge and used by the license filter | `other` means custom terms, named in `license_name` and linked in `license_link` |
| `pipeline_tag` | The task, such as `text-generation` | Decides the widget on the page and which inference APIs serve the model |
| `library_name` | The library that loads it, such as `transformers` | Repos created after August 2024 must set it, since a `config.json` alone no longer implies Transformers |
| `base_model` | One or more parent models, by Hub id | Puts the model under its parent when you filter by base model |
| `datasets` | The training datasets, by Hub id | Adds a "Datasets used to train" line with links |
| `new_version` | A newer model that replaces this one | The page links to the latest version |

## Sign in and download with the hf CLI

An **access token** is a key that lets a script act as your account. Public models download without one, but gated models refuse a request that lacks it. Signed-out requests also get the lowest **rate limits**, the number of requests the Hub accepts in each 5-minute window, counted per IP address. Past the limit, the Hub answers with error 429, the web's code for too many requests. Since version 1.2.0, the library retries those errors on its own.

Preview before you pull anything big. The docs ran `--dry-run` on the GPT-2 repository: it held 26 files, and 11 of them, 5.6G in all, were still to fetch. Most of that is one model saved again for other runtimes, as `pytorch_model.bin`, `tf_model.h5`, `flax_model.msgpack`, ONNX and TFLite files. Transformers loads **safetensors** files first, a weight format that loads without running any code, so the other copies are disk you never use.

Python has the same two moves. `hf_hub_download` fetches one file, and `snapshot_download` fetches a whole repository or only the files that match your patterns. Both return a path into the cache. With `--local-dir` you get real files in the folder you name instead, plus a small `.cache/huggingface/` folder that tracks what came from where. To freeze a download at one version, give a tag, branch or commit hash with `--revision` on the command line, or `revision=` in Python. A later push by the authors then leaves your files alone.

- **26** files in the GPT-2 repository, in the docs' dry run (Source: [Hugging Face: Download files from the Hub](https://huggingface.co/docs/huggingface_hub/guides/download), read 2026-11-05)
- **5.6G** still to download in that run, across 11 files (Source: [Hugging Face: Download files from the Hub](https://huggingface.co/docs/huggingface_hub/guides/download), read 2026-11-05)
- **548.1M** the model.safetensors weights on their own (Source: [Hugging Face: Download files from the Hub](https://huggingface.co/docs/huggingface_hub/guides/download), read 2026-11-05)

> **Slow link or no network**
>
> The download timeout is 10 seconds by default. Set `HF_HUB_DOWNLOAD_TIMEOUT=30` on a slow connection. Once the files sit in the cache, `HF_HUB_OFFLINE=1` tells the libraries to use only the cache, which suits a laptop on a train or a server with no internet access.

````bash
pip install -U "huggingface_hub"
hf auth login
hf auth whoami
hf download openai-community/gpt2 --dry-run
hf download gpt2 config.json model.safetensors
````

1. Create a virtual environment and install the library with `pip install -U "huggingface_hub"`. The CLI ships inside it.
2. Make a token. In your [Hugging Face settings](https://huggingface.co/settings/tokens), open the **Access Tokens** tab, click **New token**, then pick a role and a name. A read token covers downloads.
3. Run `hf auth login`. By default it signs you in through the browser, printing a URL and a short code. On a server, keep the token in `HF_TOKEN` and run `hf auth login --token $HF_TOKEN`, so the raw value never lands in your shell history.
4. Check the sign-in with `hf auth whoami`. It prints your username and your organizations.
5. Preview with `hf download openai-community/gpt2 --dry-run`. Nothing is written. Each file shows the bytes it would add.
6. Fetch only the files you load: `hf download gpt2 config.json model.safetensors`, as the download guide writes it. It prints the local path on its last line. The short id works because the Hub redirects `gpt2` to `openai-community/gpt2`.
7. Read that path. Without `--local-dir`, files go to the cache under `~/.cache/huggingface/hub`, or `C:\Users\username\.cache\huggingface\hub` on Windows. Set `HF_HOME` to move the cache to a bigger disk.

| Account | Hub API calls | File downloads | Web pages |
| --- | --- | --- | --- |
| Signed out, per IP address | 500 | 3,000 | 100 |
| Free account | 1,000 | 5,000 | 200 |
| PRO account | 2,500 | 12,000 | 400 |

## Gated models and token roles

A **gated model** is one whose authors want a request before the files open. [Gemma 2](https://huggingface.co/google/gemma-2-2b), the text generation example in lesson 2, is one: its page asks you to review and agree to Google's usage license first.

Requests happen in the browser, signed in. Clicking **Agree** shares your Hugging Face username and email with the authors, if they chose to collect them, plus anything you typed into their form. With automatic approval the files open at once. With manual approval you wait for the authors, and they can block your access later without notice.

Scripts need the token from the sign-in step, because a browser session does not carry over to Python. In code, `login()` from `huggingface_hub` stores a token the way the CLI does, and the download functions take a `token` argument too. On a server, setting `HF_TOKEN` is enough, since every call picks it up.

Each token has a **role**, the set of things it may do. Pick the role by what the script does. Make one token per machine or app, so revoking one leaves the rest working. A leaked token gets deleted or refreshed from the same **Access Tokens** tab.

Sharing needs a write token. To publish a model folder of your own, the getting-started page uses a single command, `hf upload your-username/your-model-name ./my-model-directory`, and the CLI deals with large files by itself. For a small change, a repository's web page has **Files**, then **Add file**.

| Role | What it can do | Use it for |
| --- | --- | --- |
| Read | Read every repository you can read, public or private | Downloads and inference calls |
| Write | Everything read does, plus push to repositories you can write to | Uploading a model or editing a model card |
| Fine-grained | Only the resources and actions you tick when you make it | Production apps, such as read access to one gated model |

## How huggingface_hub's maintainers handle rate limits and the cache

Rate limits are what most download scripts hit first. Célina Hanouti, an engineer at Hugging Face and co-maintainer of `huggingface_hub`, announced version 1.2 [on X](https://x.com/hanouticelina/status/1996958360323735611) on 5 December 2025, with smarter handling of rate limits for steadier uploads, downloads and API calls. When a script still stops on one, run `pip show huggingface_hub` and check the version before you write retry code of your own.

The cache changed in September 2026. Lucain Pouget, who maintains the library, [posted on X](https://x.com/Wauplin/status/2100585417875603856) on 17 September that version 1.32.0 shares downloaded files between repositories. His example: fetching Qwen-Image, then Qwen-Image-Edit, reused 16.8 GB of weights. Hashes are checked when a file is uploaded, which is why one copy can serve both models. His upgrade line is `hf update`.

Shared files are one more reason to clean up with the CLI and not by hand. The [CLI guide](https://huggingface.co/docs/huggingface_hub/guides/cli) says `hf cache prune` also removes shared files that no repository points to any more.

> Xet verifies file hashes on upload, making cross-repo caching safe.
>
> Lucain Pouget, Maintainer of huggingface_hub, [X](https://x.com/Wauplin/status/2100585417875603856) (read 2026-11-05)

[![Célina Hanouti (@hanouticelina) on X, 5 December 2025: Hitting 429 rate limits on the Hugging Face Hub? The new huggingface_hub Python library v1.2 makes things much smoother. We've introduced smarter rate limits handling for significantly more reliable uploads, downloads, and API calls.](https://mindket.com/blog/shots/x-hanouticelina-hub-429-rate-limits.webp?v=a9149a1ca1bc)](https://x.com/hanouticelina/status/1996958360323735611)

Célina Hanouti on X, 5 December 2025

[![Lucain Pouget (@Wauplin) on X, 17 September 2026: New in huggingface_hub v1.32.0, a shared download cache. Downloading Qwen-Image, then Qwen-Image-Edit reused 16.8 GB of weights across repos. Xet verifies file hashes on upload, making cross-repo caching safe. Update with hf update.](https://mindket.com/blog/shots/x-wauplin-shared-download-cache.webp?v=001d6ad68619)](https://x.com/Wauplin/status/2100585417875603856)

Lucain Pouget on X, 17 September 2026

> Screenshots of X's own embeds of the posts, taken on 5 November 2026, with the time in UTC. Select one to open the post on X.

## Common mistakes

- Copying `huggingface-cli` commands from an older tutorial. Version 1.0 removed that name, so translate each one: `huggingface-cli login` becomes `hf auth login`.
- Downloading a whole repository by habit. A repo can carry the same weights in five or six formats, and your code reads one of them.
- Building a product on a gated model with no plan B. The authors decide on approval and can take it back, so note an open alternative while you choose.
- Loading `.bin` weights when a safetensors copy sits next to them. Those files use pickle, a Python format the Transformers docs call insecure.
- Fetching a dataset with a plain `hf download`. The command looks for a model unless you add `--repo-type dataset`, or `--repo-type space` for a demo app.
- Pasting a raw token into a command. It stays in your shell history, which is why the CLI docs pass it through an environment variable.
- Running download scripts signed out. The rate-limit docs name a missing `HF_TOKEN` as the most common reason people hit a 429 error.
- Editing a file through the path a download returns. That path points into the cache, and changing the file corrupts it. Copy it out, or download with `--local-dir`.
- Expecting `hf auth logout` to sign a server out. While `HF_TOKEN` is set, the CLI keeps using it until you unset the variable.

## Try it yourself

These two lines are the download guide's filter example, and they need no token, since GPT-2 is public. The first pattern keeps every JSON and Markdown file. The second one skips the tokenizer's vocabulary file anyway, so you see both filters at work on one repository.

````python
from huggingface_hub import snapshot_download
snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json")
````

- Paste the lines into a Python shell, which shows the path the call returns, and list that folder. Which files from the dry run are missing, and which pattern kept each one out?
- Set `HF_HUB_OFFLINE=1` in your shell and run the snippet again. Does it still hand back a path with the network cut off?
- Run `hf download openai-community/gpt2 --include "*.json" --dry-run` and count the JSON files in the repository.
- On [the models page](https://huggingface.co/models), find a model whose card says `license: other` and open its license link. Could a paid app use it?
- Run `hf cache ls` and find GPT-2 in the list. Then remove it with `hf cache rm model/gpt2`, the CLI guide's own example, and list the cache again. What is left?

## Next

Files on disk do nothing yet. [Lesson 2](https://mindket.com/learn/hugging-face/transformers-pipeline) loads a model with one `pipeline()` call and covers the device and memory settings that decide whether it runs. Its text generation example uses the [gated Gemma 2](https://huggingface.co/google/gemma-2-2b), so request access now and the approval may be waiting when you get there. Models too big for your machine come in lesson 3, where hosted providers run them for you. Before you pick something large, the [local LLM hardware lesson](https://mindket.com/learn/local-ai/local-llm-hardware) shows how much memory each model size asks of your machine.

## Check yourself

1. Which command signs you in with the current Hugging Face CLI?

   A. huggingface-cli login
   B. hf login --password
   C. hf auth login
   D. pip login huggingface

   Answer: C. The tool was renamed to hf, sign-in moved under hf auth, and version 1.0 removed the huggingface-cli name.

2. What does adding --dry-run to hf download do?

   A. Lists each file and the bytes left to fetch, and writes nothing
   B. Downloads into a temporary folder
   C. Checks your token, then stops
   D. Re-hashes every file already in the cache

   Answer: A. A dry run shows what a download would add, so you can drop formats you will never load.

3. A model card says license: other. What do you do before using the model?

   A. Nothing, other means there are no limits
   B. Switch to the fp16 weights
   C. Create a write token
   D. Read the terms named in license_name and linked in license_link

   Answer: D. The value other marks custom terms, and only those terms say whether your use is allowed.

4. Where does hf download put files when you leave out --local-dir?

   A. In the current folder
   B. In the cache, under ~/.cache/huggingface/hub by default
   C. In your Python site-packages
   D. In a temporary folder deleted on exit

   Answer: B. Downloads go to the cache unless you pass --local-dir, and HF_HOME moves that cache.

## Frequently asked questions

### Is Hugging Face free?

Yes for the basics: an account, browsing and downloading public models cost nothing. A PRO plan raises your rate limits and adds monthly credits for hosted models. Free accounts get no monthly credits but can buy some, and lesson 4 shows where hosting a demo needs a paid plan.

### How do I delete downloaded models to free disk space?

Use the cache commands. `hf cache ls` lists what is stored, `hf cache rm` deletes the repos or revisions you name, and `hf cache prune` removes revisions nothing points to any more. Both delete commands take `--dry-run` to preview.

### Can my whole team use a gated model I have access to?

No. Access is granted to individual users, so each teammate sends a request. For a production app, the token docs suggest that a member with access creates a fine-grained token that reads that one model.

### Can I download a model with git clone instead?

Yes, since each model is a git repository, but large files need the Git Xet extension (`git xet install`). The `hf` tools handle large files with no extra setup and let you pick single files, which a clone cannot.

## Sources

- [Hugging Face Hub documentation](https://huggingface.co/docs/hub/index) (read 2026-11-05)
- [Hugging Face Hub: Model cards](https://huggingface.co/docs/hub/model-cards) (read 2026-11-05)
- [Hugging Face Hub: Licenses](https://huggingface.co/docs/hub/repositories-licenses) (read 2026-11-05)
- [Hugging Face Hub: Gated models](https://huggingface.co/docs/hub/models-gated) (read 2026-11-05)
- [Hugging Face Hub: User access tokens](https://huggingface.co/docs/hub/security-tokens) (read 2026-11-05)
- [Hugging Face Hub: Rate limits](https://huggingface.co/docs/hub/rate-limits) (read 2026-11-05)
- [Hugging Face Hub: Getting started with repositories](https://huggingface.co/docs/hub/repositories-getting-started) (read 2026-11-05)
- [huggingface_hub: Installation](https://huggingface.co/docs/huggingface_hub/installation) (read 2026-11-05)
- [huggingface_hub: Command Line Interface (CLI)](https://huggingface.co/docs/huggingface_hub/guides/cli) (read 2026-11-05)
- [Hugging Face: Download files from the Hub](https://huggingface.co/docs/huggingface_hub/guides/download) (read 2026-11-05)
- [huggingface_hub: Migrating to v1.0](https://huggingface.co/docs/huggingface_hub/concepts/migration) (read 2026-11-05)
- [Hugging Face blog: Say hello to hf](https://huggingface.co/blog/hf-cli) (read 2026-11-05)
- [Transformers: Installation](https://huggingface.co/docs/transformers/installation) (read 2026-11-05)
- [Transformers: Loading models](https://huggingface.co/docs/transformers/models) (read 2026-11-05)
- [Inference Providers: Pricing and billing](https://huggingface.co/docs/inference-providers/pricing) (read 2026-11-05)
- [Hugging Face: google/gemma-2-2b model page](https://huggingface.co/google/gemma-2-2b) (read 2026-11-05)
- [Célina Hanouti on X: huggingface_hub v1.2 and 429 rate limits](https://x.com/hanouticelina/status/1996958360323735611) (read 2026-11-05)
- [Lucain Pouget on X: a shared download cache in huggingface_hub v1.32.0](https://x.com/Wauplin/status/2100585417875603856) (read 2026-11-05)

[Browse GitHub projects](https://mindket.com/github)