gem-hunter
Language: Python
The official CLI and Python client for the Hugging Face Hub.
The official CLI and Python client for the Hugging Face Hub.
About
·
Documentation
·
Install
·
CLI Guide
·
Contributing
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.
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:
hf CLI.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 addLearn more in the Hugging Face CLI for AI agents guide and the announcement blog post.
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 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.
from huggingface_hub import create_repo create_repo(repo_id="super-cool-model")
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.
We're partnering with cool open source ML libraries to provide free model hosting and versioning. You can find the existing integrations here.
The advantages are:
If you would like to integrate your library, feel free to open an issue to begin the discussion. We wrote a step-by-step guide with ❤️ showing how to do this integration.
Everyone is welcome to contribute, and we value everybody's contribution. Code is not the only way to help the community. Answering questions, helping others, reaching out and improving the documentations are immensely valuable to the community. We wrote a contribution guide to summarize how to get started to contribute to this repository.