hf-hub

hf-hub is a typed, ergonomic Rust client for the Hugging Face Hub API, serving as the Rust equivalent of the Python huggingface_hub library. It covers repository, file, commit, branch/tag, bucket, and user/organization operations against the Hub, including support for Hugging Face’s high-performance Xet storage backend.

The crate ships both an async interface (HFClient) built on tokio and reqwest, and a synchronous interface (HFClientSync) for callers that don’t want to manage their own async runtime, alongside a companion hfrs CLI for terminal-based Hub interaction.

What You Get

• Async (HFClient) and blocking (HFClientSync) client interfaces that mirror each other method-for-method
• Repository operations: query/create/delete/update/move models, datasets, and spaces
• File and commit operations including streaming uploads, downloads, and revision diffs
• Streaming pagination via impl Stream<Item = Result<T>> for memory-efficient async listing
• Support for Hugging Face’s Xet high-performance transfer backend and bucket storage operations

Common Use Cases

• Downloading model weights and dataset files from the Hugging Face Hub in a Rust application
• Automating repository and branch/tag management for models hosted on the Hub
• Building Rust ML tooling (e.g. inference servers) that needs to fetch artifacts from the Hub at runtime
• Scripting Hub operations via the bundled hfrs CLI instead of the Python huggingface-cli
• Uploading large model files efficiently using Xet-backed transfers

Under The Hood

Architecture - The repo is a Cargo workspace (hf-hub, hfrs CLI, benches, examples, integration-tests) where the hf-hub crate exposes HFClient (async, default) and HFClientSync (blocking, feature-gated) that both delegate to shared request-building logic in client.rs, with domain modules split by resource: repository/, buckets/, spaces.rs, users.rs, and a dedicated xet.rs for Hugging Face’s high-throughput transfer protocol. Tech Stack - Built on reqwest for HTTP, tokio for async execution, bon for builder-pattern request construction, serde/serde_json for (de)serialization, and thiserror for structured error types, targeting Rust 2024 edition. Code Quality - The workspace separates unit tests colocated with modules from a dedicated integration-tests crate covering blocking calls, bucket sync/streaming/Xet transfers, downloads, and caching, indicating deliberate coverage of both the sync and async surfaces against real Hub behavior. API Design - The parallel HFClient/HFClientSync design lets callers pick sync or async without learning two different APIs, and the builder-style request pattern (.model(...).info().send().await?) keeps call sites readable, though the breadth of resource types (repos, buckets, spaces, users) means newcomers need to learn several submodules to use the client fully.