pypi huggingface-hub 1.5.0
[v1.5.0]: Buckets API, Agent-first CLI, Spaces Hot-Reload and more
on Python PyPI

6 hours ago

This release introduces major new features including Buckets (xet-based large scale object storage), CLI Extensions, Space Hot-Reload, and significant improvements for AI coding agents. The CLI has been completely overhauled with centralized error handling, better help output, and new commands for collections, papers, and more.

🪣 Buckets: S3-like Object Storage on the Hub

Buckets provide S3-like object storage on Hugging Face, powered by the Xet storage backend. Unlike repositories (which are git-based and track file history), buckets are remote object storage containers designed for large-scale files with content-addressable deduplication. Use them for training checkpoints, logs, intermediate artifacts, or any large collection of files that doesn't need version control. 

# Create a bucket
hf buckets create my-bucket --private

# Upload a directory
hf buckets sync ./data hf://buckets/username/my-bucket

# Download from bucket
hf buckets sync hf://buckets/username/my-bucket ./data

# List files
hf buckets list username/my-bucket -R --tree

The Buckets API includes full CLI and Python support for creating, listing, moving, and deleting buckets; uploading, downloading, and syncing files; and managing bucket contents with include/exclude patterns.

📚 Documentation: Buckets guide

🤖 AI Agent Support

This release includes several features designed to improve the experience for AI coding agents (Claude Code, OpenCode, Cursor, etc.):

  • Centralized CLI error handling: Clean user-facing messages without tracebacks (set HF_DEBUG=1 for full traces) by @hanouticelina in #3754
  • Token-efficient skill: The hf skills add command now installs a compact skill (~1.2k tokens vs ~12k before) by @hanouticelina in #3802
  • Agent-friendly hf jobs logs: Prints available logs and exits by default; use -f to stream by @davanstrien in #3783
  • Add AGENTS.md: Dev setup and codebase guide for AI agents by @Wauplin in #3789 
# Install the hf-cli skill for Claude
hf skills add --claude

# Install for project-level
hf skills add --project

🔥 Space Hot-Reload (Experimental)

Hot-reload Python files in a Space without a full rebuild and restart. This is useful for rapid iteration on Gradio apps. 

# Open an interactive editor to modify a remote file
hf spaces hot-reload username/repo-name app.py

# Take local version and patch remote
hf spaces hot-reload username/repo-name -f app.py

🖥️ CLI Improvements

New Commands

  • Add hf papers ls to list daily papers on the Hub by @julien-c in #3723
  • Add hf collections commands (ls, info, create, update, delete, add-item, update-item, delete-item) by @Wauplin in #3767

CLI Extensions

Introduce an extension mechanism to the hf CLI. Extensions are standalone executables hosted in GitHub repositories that users can install, run, and remove with simple commands. Inspired by gh extension. 

# Install an extension (defaults to huggingface org)
hf extensions install hf-claude

# Install from any GitHub owner
hf extensions install hanouticelina/hf-claude

# Run an extension
hf claude

# List installed extensions
hf extensions list

Output Format Options

  • Add --format {table,json} and -q/--quiet to hf models ls, hf datasets ls, hf spaces ls, hf endpoints ls by @hanouticelina in #3735
  • Align hf jobs ps output with standard CLI pattern by @davanstrien in #3799
  • Dynamic table columns based on --expand field by @hanouticelina in #3760

Usability

Jobs CLI

List available hardware: 

✗ hf jobs hardware
NAME            PRETTY NAME            CPU      RAM     ACCELERATOR       COST/MIN COST/HOUR 
--------------- ---------------------- -------- ------- ----------------- -------- --------- 
cpu-basic       CPU Basic              2 vCPU   16 GB   N/A               $0.0002  $0.01     
cpu-upgrade     CPU Upgrade            8 vCPU   32 GB   N/A               $0.0005  $0.03     
cpu-performance CPU Performance        32 vCPU  256 GB  N/A               $0.3117  $18.70    
cpu-xl          CPU XL                 16 vCPU  124 GB  N/A               $0.0167  $1.00     
t4-small        Nvidia T4 - small      4 vCPU   15 GB   1x T4 (16 GB)     $0.0067  $0.40     
t4-medium       Nvidia T4 - medium     8 vCPU   30 GB   1x T4 (16 GB)     $0.0100  $0.60     
a10g-small      Nvidia A10G - small    4 vCPU   15 GB   1x A10G (24 GB)   $0.0167  $1.00  
...

Also added a ton of fixes and small QoL improvements.

🤖 Inference

  • Add dimensions & encoding_format parameter to InferenceClient for output embedding size by @mishig25 in #3671
  • feat: zai-org provider supports text to image by @tomsun28 in #3675
  • Fix fal image urls payload by @hanouticelina in #3746
  • Fix Replicate image-to-image compatibility with different model schemas by @hanouticelina in #3749
  • Accelerator parameter support for inference endpoints by @Wauplin in #3817

🔧 Other QoL Improvements

💔 Breaking Changes

  • hf jobs ps removes old Go-template --format '{{.id}}' syntax. Use -q for IDs or --format json | jq for custom extraction by @davanstrien in #3799
  • Migrate to hf repos instead of hf repo (old command still works but shows deprecation warning) by @Wauplin in #3848
  • Migrate hf repo-files delete to hf repo delete-files (old command hidden from help, shows deprecation warning) by @Wauplin in #3821

🐛 Bug and typo fixes

  • Fix severe performance regression in streaming by keeping a byte iterator in HfFileSystemStreamFile by @leq6c in #3685
  • Fix endpoint not forwarded in CommitUrl by @Wauplin in #3679
  • Fix HfFileSystem.resolve_path() with special char @ by @lhoestq in #3704
  • Fix cache verify incorrectly reporting folders as missing files by @Mitix-EPI in #3707
  • Fix multi user cache lock permissions by @hanouticelina in #3714
  • Default _endpoint to None in CommitInfo, fixes tiny regression from v1.3.3 by @tomaarsen in #3737
  • Filter datasets by benchmark:official by @Wauplin in #3761
  • Fix file corruption when server ignores Range header on download retry by @XciD in #3778
  • Fix Xet token invalid on repo recreation by @Wauplin in #3847
  • Correct typo 'occured' to 'occurred' by @thecaptain789 in #3787
  • Fix typo in CLI error handling by @hanouticelina in #3757

📖 Documentation

🏗️ Internal

Check out latest releases or
releases around huggingface-hub 1.5.0

Don't miss a new huggingface-hub release

NewReleases is sending notifications on new releases.

Get notifications