huggingface_hub 2.0 to 2.2: Upgrade Notes for HTTP, Jobs and CLI Changes

The changes at a glance #

The table below lists the main changes by release, using only what each version's release notes state. The release notes for v2.0.0, v2.1.0 and v2.2.0 are the sources for each row.

v2.0.0: the httpx2 break #

According to the v2.0.0 release notes, clients and transport exceptions now come from httpx2 and httpcore2 instead of httpx and httpcore. Custom client factories registered through set_client_factory or set_async_client_factory must use httpx2 types, and so must any except clause that catches transport errors. The notes recommend importing the HTTP module from huggingface_hub.utils when code has to run on both v1.x (starting with v1.30.0) and v2.x:

from huggingface_hub.utils import get_session, httpx

try:
    response = get_session().get("https://huggingface.co/api/models/gpt2")
    response.raise_for_status()
    print(response.status_code)
except httpx.HTTPError as exc:
    print(f"request failed: {exc}")

Three operational details from the same notes deserve attention during an upgrade. httpx2 uses the operating system's certificate trust store by default, though custom CA bundles set through SSL_CERT_FILE and SSL_CERT_DIR still work. Logging configuration should target the httpx2 and httpcore2 loggers. The oauth extra now requires authlib>=1.8.0.

Removed APIs and CLI entry points #

The v2.0.0 notes also state that every API deprecated in 1.x is removed. The Python list includes upload_large_folder (use upload_folder), duplicate_space (use duplicate_repo), the Space storage calls (use the volume APIs), list_models(model_name=...) (use search), and text_generation(stop_sequences=...) (use stop). Passing type="protected" to create_inference_endpoint now raises ValueError, so the replacement is AUTHENTICATED.

On the CLI side, the notes say the following are gone: huggingface-cli, which is replaced by hf; hf repo and hf repo-files delete, replaced by hf repos and hf repos delete-files; hf upload-large-folder, replaced by hf upload; and the --storage option on hf repos create and hf repos duplicate, replaced by --volume.

The Jobs listing commands need a precise reading. The notes do not remove hf jobs ps or hf jobs scheduled ps. They remove only the -f/--filter option from both, and the replacements are --status and --label. Scripts that call those commands without the filter flag are not affected by that entry. The notes also remove the --claude flag from hf skills add and hf skills update, stating that Claude Code installation is now automatic. A migration guide covering these changes is linked from the same release notes at https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/concepts/migration_v2.md.

v2.1.0: Jobs, quota and the catalog #

The v2.1.0 release notes describe several Jobs changes. A Job can retry automatically on failure with the new attempts parameter. A new Job can be started from an existing Job's saved spec, including secrets and hardware settings, with rerun_job or hf jobs rerun. Scheduled Jobs can change their cron expression or preset through update_scheduled_job_schedule or hf jobs scheduled reschedule, without being recreated. Ports can be exposed with expose for token-protected access or expose_public for unauthenticated access, both at creation time and on a running Job.

The ZeroGPU quota change is a new HfApi.get_zero_gpu_quota() method that returns a ZeroGpuQuota dataclass, with values in GPU-seconds. The notes suggest it for apps, MCP servers and agents built on ZeroGPU Spaces, so they can warn users before the daily limit. The v2.1.0 notes show the CLI command as hf spaces zero-gpu-quota. They also list a rename to hf spaces zero-gpu quota and mark it as shipped as part of v2.1.1. Readers on v2.1.0 should use the hyphenated name, and readers on v2.1.1 or later should use the spaced name. The notes do not say more about the v2.1.1 release itself.

The Inference Endpoints catalog methods move to the new /api/v1/catalog API. list_inference_catalog returns InferenceCatalogModel dataclasses that include tested deployment recipes, and it accepts server-side filters. The CLI gains matching options on hf endpoints catalog ls, plus --recipe and --gguf-file on hf endpoints catalog deploy.

Two other v2.1.0 items are breaking. Pooled sandboxes with missing, empty or malformed capability tokens are now refused, and the client is pinned to sbx-server 0.7.0. Older pool hosts that do not provide scoped tokens must be upgraded or recycled, and the notes say that new clients cannot reach legacy hosts. Bucket include and exclude patterns are now case-sensitive on all platforms.

The v2.1.0 notes also show a file download change. HfFileSystem.get_file downloads Xet-backed files through hf_xet when writing to a local path. The notes report Jobs benchmarks of about 120 seconds down to 7 seconds for a 2 GB parquet file. Those figures come from the release notes and were not measured independently for this article.

v2.2.0: snapshots and cache correctness #

The v2.2.0 release notes describe the most consequential behaviour change in this series. hf jobs stats used to stream metrics until the job finished, so scripts and agents calling it on a running job hung until their own timeout. It now prints the latest sample of each job once and exits, in the same way as hf jobs logs. The previous live view is available through -f or --follow. The snapshot output also accepts --format json|agent|quiet, which prints the raw API metrics.

# One snapshot, then exit (new default)
hf jobs stats <job_id>

# Stream live stats until the job completes (previous behaviour)
hf jobs stats -f <job_id>

On the Python side, HfApi.fetch_job_metrics gets a follow parameter that matches fetch_job_logs. It defaults to False and returns only the current sample. Passing follow=True restores streaming until the job completes. The release notes list this as a breaking change.

The notes also describe a race in the first concurrent calls to hf_hub_download in a fresh process. Those calls could read a placeholder version for hf_xet while another thread was still resolving it, and then fall back to plain HTTP. The version lookup is now cached only once it is resolved. The notes say this mostly affected parallel downloads such as snapshot_download.

HfFileSystem received three cache fixes. ls() on a newly created empty bucket returns an empty list instead of raising FileNotFoundError. Directory listings are replaced in the cache rather than appended to, which the notes say could previously produce duplicate entries. exists(path, refresh=True) and invalidate_cache(path) now clear cached not-found results, so a repo, branch or bucket created in the same process is no longer reported as missing.

On Windows, the v2.2.0 notes say the CLI no longer glob-expands arguments. Quoted patterns such as --exclude ".venv/**" were previously expanded into local file names before reaching the command. The notes give an example where hf download with --include "*.json" silently downloaded nothing in a folder that contained a .json file. Scripts that worked around the old behaviour should be re-tested.

Checking the CLI changes against the notes #

The CLI is where errors are easiest to make, so each command named in this article is checked against the three release notes. hf jobs ps and hf jobs scheduled ps remain available, and only their -f/--filter option is removed in v2.0.0. hf jobs stats changes default behaviour in v2.2.0, and -f/--follow is the v2.2.0 way to keep the live view. hf spaces zero-gpu-quota is named in v2.1.0, with the spaced name listed for v2.1.1. Windows glob handling is a v2.2.0 change. The v2.0.0 notes contain the removals of huggingface-cli, hf upload-large-folder, the Repo command renames, and the --claude flag on the skills commands.

Upgrade checklist #

1. Read the migration guide linked from the v2.0.0 release notes, and list every removed API and CLI entry point that your code uses.
2. Move custom client factories and transport exception handling to httpx2 types, or import httpx from huggingface_hub.utils if the code must support both v1.x and v2.x.
3. Retarget logging configuration to the httpx2 and httpcore2 loggers, check custom CA settings, and confirm authlib is at least 1.8.0 if you use oauth.
4. Replace hf jobs ps and hf jobs scheduled ps filters that used -f/--filter with --status or --label.
5. Adopt --attempts, hf jobs rerun, rescheduling and hf jobs expose in Jobs workflows where they fit.
6. Use the quota command name that matches your version, and check the v2.1.1 rename if you script ZeroGPU quota checks.
7. Update catalog calls for the /api/v1 API, and confirm that sandbox pool hosts provide scoped tokens.
8. Check bucket include and exclude patterns for case assumptions.
9. Add -f or follow=True wherever a script relied on streaming Jobs metrics.
10. Re-test Windows CLI commands that pass quoted glob patterns, and re-test parallel downloads and HfFileSystem flows, using refresh=True after creating repos in the same process.