Crate hf_hub 

hf-hub

Async Rust client for the Hugging Face Hub API — the Rust counterpart to the Python huggingface_hub library.

The crate exposes a high-level, ergonomic API built around a single entry point, HFClient, and a family of typed handles (HFRepository<T>, HFBucket) that scope operations to a specific resource. The repo kind lives in the type system via the RepoType trait and its four marker structs (RepoTypeModel, RepoTypeDataset, RepoTypeSpace, RepoTypeKernel). All network I/O is async and driven by the reqwest HTTP client with built-in retries on transient failures.

Quick start

use hf_hub::HFClient;

#[tokio::main]
async fn main() -> hf_hub::HFResult<()> {
    let client = HFClient::new()?;
    let info = client.model("openai-community", "gpt2").info().send().await?;
    println!("Repo: {:?}", info);
    Ok(())
}

Feature overview

• Repositories — read info, list contents, create, delete, move, and update settings for models, datasets, and Spaces.
• Files — list, download (with optional local cache or local_dir), upload single files or whole folders, and build multi-operation commits.
• Commits & refs — paginate commit history, compute diffs between revisions, and manage branches and tags.
• Users & orgs — whoami, authentication checks, profile lookup, and follower/following lists.
• Spaces — runtime, hardware, secrets, variables, pause/restart.
• Buckets — namespaced storage buckets, tree listings, and bucket sync plans.
• Xet transfers — high-performance chunk-deduplicated uploads and downloads integrated transparently into the file APIs.
• Optional blocking API — synchronous counterparts to every async handle when the blocking feature is enabled.

Creating a client

HFClient::new() resolves configuration from the environment:

Variable	Purpose
HF_TOKEN	Authentication token (preferred source)
HF_TOKEN_PATH	Path to a file containing the token
HF_ENDPOINT	Override the Hub base URL
HF_HOME	Root for Hugging Face state (defaults to ~/.cache/huggingface)
HF_HUB_CACHE	Cache directory for downloaded files
HF_HUB_DISABLE_IMPLICIT_TOKEN	Ignore the ambient HF_TOKEN/token file

For explicit configuration use HFClient::builder():

use hf_hub::HFClient;

let client = HFClient::builder()
    .token("hf_xxx")
    .endpoint("https://huggingface.co")
    .cache_dir("/tmp/hf-cache")
    .build()?;

HFClient wraps an Arc<…> internally, so cloning it is cheap and all clones share the same connection pool, token, and cache configuration.

Repository handles

Rather than passing (repo_type, owner, name) to every method, bind them once with a typed handle. The repo kind is encoded in the type via a marker (RepoTypeModel, RepoTypeDataset, RepoTypeSpace, RepoTypeKernel):

use hf_hub::HFClient;

let client = HFClient::new()?;

let model = client.model("openai-community", "gpt2");
let dataset = client.dataset("HuggingFaceFW", "fineweb");
let space = client.space("huggingface", "diffusers-gallery");
let kernel = client.kernel("kernels-community", "cutlass-mla");

let exists = model.exists().send().await?;

Space-specific methods like runtime, add_secret, and pause live as impl blocks on HFRepository<RepoTypeSpace> — there is no separate HFSpace wrapper.

When you start from a single "owner/name" string, split_id turns it into the (owner, name) pair these constructors take (short-form ids like "gpt2" yield an empty owner):

use hf_hub::{HFClient, split_id};

let client = HFClient::new()?;
let (owner, name) = split_id("openai-community/gpt2");
let model = client.model(owner, name);

File operations

File APIs live on the repository handle. Downloads go through the local cache by default, producing a path that is safe to read from even across concurrent calls:

use hf_hub::HFClient;

let client = HFClient::new()?;
let path = client
    .model("openai-community", "gpt2")
    .download_file()
    .filename("config.json")
    .send()
    .await?;
println!("cached at {}", path.display());

Uploads accept bytes, files, or entire folders, and can be batched into a single commit via HFRepository::create_commit with repository::CommitOperations.

Pagination

Endpoints that return a stream of results — commit history, repo listings, recursive tree walks — return impl Stream<Item = Result<T>>. Use the futures::StreamExt adapters to iterate:

use futures::StreamExt;
use hf_hub::HFClient;

let client = HFClient::new()?;
let model = client.model("openai-community", "gpt2");
let stream = model.list_tree().recursive(true).send()?;
futures::pin_mut!(stream);
while let Some(entry) = stream.next().await {
    println!("{:?}", entry?);
}

Blocking API

Enable the blocking feature for synchronous wrappers that manage a dedicated tokio runtime internally. The runtime lives on a background thread, so the blocking methods are safe to call even from inside another tokio runtime:

[dependencies]
hf-hub = { version = "1", features = ["blocking"] }

#[cfg(feature = "blocking")]
fn main() -> Result<(), hf_hub::HFError> {
    use hf_hub::HFClientSync;

    let client = HFClientSync::new()?;
    let _info = client.model("openai-community", "gpt2").info().send()?;
    Ok(())
}

#[cfg(not(feature = "blocking"))]
fn main() {}

The blocking handles (HFClientSync, HFRepositorySync, HFBucketSync) mirror their async counterparts method-for-method.

Errors

All fallible operations return Result<T> = Result<T, HFError>. HFError distinguishes common Hub conditions — RepoNotFound, EntryNotFound, RevisionNotFound, AuthRequired, Forbidden, and RateLimited — so you can match on them directly without parsing HTTP status codes or response bodies.

Caching

Downloads are content-addressed under HF_HUB_CACHE, with on-disk locking so concurrent fetches of the same file deduplicate. Disable caching with HFClientBuilder::cache_enabled(false), or bypass it per-request by setting .local_dir(...) on the download builder. Use HFClient::scan_cache to inspect what’s cached on disk.

Cargo features

• blocking — enables the synchronous *Sync handles.
• socks — enables SOCKS proxy support in the underlying HTTP client (forwards to reqwest/socks).

Modules

buckets

Bucket handles and file operations for Hugging Face Hub buckets.

cacheNon-target_family=wasm

Inspect the local Hugging Face cache.

progress

Progress reporting for upload and download operations.

repository

Repository handles, metadata types, and list/create/delete/move APIs.

spaces

Space handles, response types, and runtime/hardware/secrets APIs.

users

Users and organizations: identity, profile lookup, and social listings.

Structs

HFBucket

A handle for a single bucket on the Hugging Face Hub.

HFBucketSyncblocking

Synchronous/blocking counterpart to crate::buckets::HFBucket.

HFClient

Async client for the Hugging Face Hub API.

HFClientBuilder

Builder for HFClient.

HFClientSyncblocking

Synchronous/blocking counterpart to HFClient.

HFRepository

A handle for a single repository on the Hugging Face Hub, parameterized by the repo kind via the type-level marker T.

HFRepositorySyncblocking

Synchronous/blocking counterpart to HFRepository, parameterized by the repo kind via T.

RepoTypeDataset

Dataset-repository marker. See RepoType for the trait, the per-kind string table, and usage examples; use HFClient::dataset for the typed shortcut.

RepoTypeKernel

Kernel-repository marker. See RepoType for the trait, the per-kind string table, and usage examples; use HFClient::kernel for the typed shortcut. Note that HFRepository::<RepoTypeKernel>::info returns a slim shape — to get full model-style metadata for a kernel repo, build a model handle for the same id and call info() on that.

RepoTypeModel

Model-repository marker. See RepoType for the trait, the per-kind string table, and usage examples; use HFClient::model for the typed shortcut.

RepoTypeSpace

Space-repository marker. See RepoType for the trait, the per-kind string table, and usage examples; use HFClient::space for the typed shortcut. This is the marker used to access Space-only methods on HFRepository such as runtime and pause.

Enums

HFError

Error type returned by public hf-hub APIs.

RepoTypeAny

Runtime-tagged repository kind. Holds an enum value rather than encoding the kind in the type system — useful when the kind is decided at runtime (CLI flag, config string, upstream enum) and you don’t want to thread a type parameter through downstream code.

XetOperation

Identifies the xet operation associated with an HFError::Xet error.

Traits

RepoType

Type-level marker for a Hugging Face Hub repo kind (model, dataset, Space, or kernel).

Functions

split_id

Split a repo or bucket id into its (owner, name) parts.

Type Aliases

HFResult

Convenience alias used by public hf-hub APIs.