hf-release-notes

Quick start

Install the hf CLI with the standalone installer:

# On macOS and Linux.
curl -LsSf https://hf.co/cli/install.sh | bash

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

Log in, then start working with the Hub:

# Log in (use --token $HF_TOKEN in non-interactive environments)
hf auth login

# Find models served by Inference Providers
hf models ls --warm

# Download a model
hf download Qwen/Qwen3-0.6B

# Upload files to your own repo
hf upload username/my-cool-model ./model.safetensors

# Sync a local folder to a storage bucket
hf buckets sync ./checkpoints hf://buckets/username/my-bucket

# Run a job on Hugging Face infrastructure
hf jobs run python:3.12 python -c "print('Hello from the cloud!')"

# Discover everything else
hf --help

The Hub uses tokens to authenticate applications (see docs). Check out the CLI guide for a tour of the main features.

What is huggingface_hub?

The huggingface_hub library allows you to interact with the Hugging Face Hub, a platform democratizing open-source Machine Learning for creators and collaborators. Discover pre-trained models and datasets for your projects, play with the thousands of machine learning apps hosted on the Hub, or create and share your own models, datasets and demos with the community. Everything ships in one package with two interfaces: the hf CLI for your terminal and the huggingface_hub library for Python — both designed to work well for humans and AI agents. Use them to:

• Download files from the Hub.
• Upload files to the Hub.
• Manage your repositories.
• Run Inference on deployed models.
• Run Jobs on Hugging Face infrastructure.
• Search for models, datasets and Spaces.
• Share Model Cards to document your models.
• Engage with the community through PRs and comments.
• Do all of the above from the terminal with the hf CLI.

Built for humans and AI agents

The hf CLI is designed for people and coding agents alike: the same commands adapt their output when run by an agent. If you use Claude Code, Codex, Cursor, or another coding agent, install the hf CLI Skill — a command reference generated from your installed CLI:

# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add

Learn more in the Hugging Face CLI for AI agents guide and the announcement blog post.

Use the Python library

Install the huggingface_hub package with pip (this also installs the hf CLI):

pip install huggingface_hub

We recommend using uv for a fast and reliable install:

uv pip install huggingface_hub

In order to keep the package minimal by default, huggingface_hub comes with optional dependencies useful for some use cases. For example, if you want to use the MCP module, run:

pip install "huggingface_hub[mcp]"

To learn more about installation and optional dependencies, check out the installation guide.

Download files

Download a single file

from huggingface_hub import hf_hub_download

hf_hub_download(repo_id="zai-org/GLM-5.2", filename="config.json")

Or an entire repository

from huggingface_hub import snapshot_download

snapshot_download("sentence-transformers/all-MiniLM-L6-v2")

Files will be downloaded in a local cache folder. More details in this guide.

Create a repository

from huggingface_hub import create_repo

create_repo(repo_id="super-cool-model")

Upload files

Upload a single file

from huggingface_hub import upload_file

upload_file(
    path_or_fileobj="/home/lysandre/dummy-test/README.md",
    path_in_repo="README.md",
    repo_id="lysandre/test-model",
)

Or an entire folder

from huggingface_hub import upload_folder

upload_folder(
    folder_path="/path/to/local/space",
    repo_id="username/my-cool-space",
    repo_type="space",
)

More details in the upload guide.

Integrating with the Hub.

We