Introduction

Hugging Face hosts over half a million models spanning NLP, computer vision, audio, and more. Whether you are building a model search tool, auditing available architectures, or simply exploring what exists, you need a programmatic way to list and filter those models. Python gives you two clean paths: the official huggingface_hub library and the raw HTTP API.

Using the huggingface_hub Library

The recommended approach is the huggingface_hub package, which wraps the Hugging Face REST API in a convenient Python interface. Install it first:

pip install huggingface_hub

The central class is HfApi, and its list_models() method returns an iterator of model objects:

1from huggingface_hub import HfApi
2
3api = HfApi()
4
5# Fetch all models (returns an iterator)
6models = api.list_models()
7
8for model in models:
9    print(model.id, model.downloads, model.tags)

Each model object carries metadata such as id, author, downloads, likes, pipeline_tag, tags, and last_modified. Because the Hub hosts hundreds of thousands of models, iterating over every single one takes time. In practice you almost always want to filter.

Filtering Models by Task, Author, and Library

The real power of list_models() comes from its keyword arguments that let the server do the heavy lifting. Why filter server-side? Because downloading the entire model catalog just to discard 99% of it locally wastes both time and bandwidth.

1# Models for a specific task
2text_gen_models = api.list_models(task="text-generation")
3
4# Models by a specific author or organization
5meta_models = api.list_models(author="meta-llama")
6
7# Models compatible with a specific library
8onnx_models = api.list_models(library="onnx")
9
10# Combine filters and sort by popularity
11filtered = api.list_models(
12    task="text-classification",
13    author="google",
14    library="pytorch",
15    sort="downloads",
16    direction=-1,
17    limit=20,
18)
19
20for m in filtered:
21    print(f"{m.id:50s} downloads={m.downloads}")

You can also search by free-text query or by tags:

1# Free-text search
2results = api.list_models(search="sentiment")
3
4# Filter by tags
5results = api.list_models(tags=["license:mit", "language:en"])

The Deprecated transformers.list_models() Approach

Older tutorials may reference transformers.list_models(). This function was removed in recent versions of the transformers library. If you encounter it in legacy code, replace it with huggingface_hub.HfApi().list_models(), which provides the same functionality with better filtering support and is actively maintained.

Using the HTTP API Directly

If you prefer to avoid adding a dependency, you can call the REST API with requests. The endpoint is https://huggingface.co/api/models:

1import requests
2
3params = {
4    "filter": "text-generation",
5    "sort": "downloads",
6    "direction": "-1",
7    "limit": 10,
8}
9
10response = requests.get("https://huggingface.co/api/models", params=params)
11response.raise_for_status()
12models = response.json()
13
14for m in models:
15    print(m["modelId"], m.get("downloads"))

The API returns JSON arrays. For pagination, use the Link header to walk through large result sets page by page.

Handling Pagination for Large Result Sets

The Hub caps responses at a default page size. The huggingface_hub library handles pagination automatically through its iterator, so you can loop without worrying about pages. With the raw HTTP API you must follow pagination manually:

1import requests
2
3url = "https://huggingface.co/api/models"
4all_models = []
5
6while url:
7    response = requests.get(url, params={"limit": 1000})
8    response.raise_for_status()
9    all_models.extend(response.json())
10    # The 'next' link lives in the Link header
11    url = response.links.get("next", {}).get("url")
12
13print(f"Total models fetched: {len(all_models)}")

Accessing Model Card Metadata

Each model on the Hub has a model card with structured metadata. You can retrieve it with model_info() when you need details beyond what list_models() returns:

1from huggingface_hub import HfApi
2
3api = HfApi()
4info = api.model_info("bert-base-uncased")
5
6print("Pipeline tag:", info.pipeline_tag)
7print("Library:", info.library_name)
8print("Tags:", info.tags)
9print("Card data:", info.card_data)

This is especially useful for inspecting license information, dataset references, evaluation metrics, or the full README content of a specific model.

Common Pitfalls

• Iterating all models without filters can take many minutes and consume significant memory. Always apply task, author, or tag filters when possible.
• Using the deprecated transformers.list_models() will raise an ImportError on newer versions. Switch to huggingface_hub.
• Ignoring pagination with the HTTP API means you only get the first page of results, silently missing thousands of models.
• Assuming model metadata is always complete leads to KeyError crashes. Many community models have sparse or missing card data, so always use .get() with defaults.
• Making rapid unauthenticated requests triggers rate limits. Pass your token via HfApi(token="hf_...") or set the HF_TOKEN environment variable to get higher rate limits.

Summary

• Use huggingface_hub.HfApi().list_models() as the primary method to list models programmatically.
• Filter server-side by task, author, library, tags, and search to avoid downloading the entire catalog.
• The raw HTTP API at https://huggingface.co/api/models works when you want to avoid extra dependencies, but you must handle pagination yourself.
• Access detailed model card metadata with api.model_info("model-name") for license, dataset, and evaluation details.
• Always handle missing metadata gracefully and authenticate your requests to avoid rate limits.