hf-hub

Features

• Repository operations — query model, dataset, and space metadata; create, delete, update, and move repositories
• File operations — upload files and folders, download files, list repository trees, check file existence
• Commit operations — create commits with multiple file operations, list commit history, view diffs between revisions
• Branch and tag management — create and delete branches and tags, list refs
• User and organization info — whoami, user profiles, organization details, followers
• Streaming pagination — async list endpoints return impl Stream<Item = Result<T>> for lazy, memory-efficient iteration; blocking counterparts collect into Vec<T>
• Bucket operations — create, delete, list, and move buckets; upload, download, and delete files within buckets
• Xet high-performance transfers — support for Hugging Face's Xet storage backend
• Async or blocking — use HFClient with your own tokio runtime, or HFClientSync for synchronous callers (requires the blocking feature)

Installation

Add to your Cargo.toml:

[dependencies]
hf-hub = "1.0.0"

To use the synchronous interface, enable the blocking feature:

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

CLI Installation

The hfrs command-line tool provides a terminal interface to the Hub. Install it with:

cargo install --git https://github.com/huggingface/hf-hub.git hfrs

This builds in release mode by default. Once installed, run hfrs --help to see available commands.

Quick Start

Async

use hf_hub::HFClient;

#[tokio::main]
async fn main() -> hf_hub::HFResult<()> {
    let client = HFClient::new()?;

    // Get model info
    let Ok(info) = client.model("openai-community", "gpt2").info().send().await else {
        unreachable!("handle type guarantees the Model variant");
    };

    println!("Model: {} (downloads: {:?})", info.id, info.downloads);

    Ok(())
}

Blocking

Requires the blocking feature. HFClientSync manages a dedicated tokio runtime internally, so callers do not need their own.

use hf_hub::HFClientSync;

fn main() -> hf_hub::HFResult<()> {
    let client = HFClientSync::new()?;

    let Ok(info) = client.model("openai-community", "gpt2").info().send() else {
        unreachable!("handle type guarantees the Model variant");
    };
    println!("Model: {} (downloads: {:?})", info.id, info.downloads);

    Ok(())
}

The blocking handles (HFClientSync, HFRepositorySync, HFSpaceSync, HFBucketSync) mirror their async counterparts method-for-method. See the blocking_* examples in examples/ for runnable programs.

Usage Examples

List models by author

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

#[tokio::main]
async fn main() -> hf_hub::HFResult<()> {
    let client = HFClient::new()?;

    let stream = client
        .list_models()
        .author("meta-llama")
        .limit(5_usize)
        .send()?;
    futures::pin_mut!(stream);

    while let Some(model) = stream.next().await {
        let model = model?;
        println!("{}", model.id);
    }

    Ok(())
}

Work with a repository handle

use hf_hub::HFClient;

#[tokio::main]
async fn main() -> hf_hub::HFResult<()> {
    let client = HFClient::new()?;
    let repo = client.model("openai-community", "gpt2");

    let Ok(model_info) = repo.info().send().await else {
        println!("error, not a model");
        return Ok(());
    };
    println!("Model: {}", model_info.id);

    let exists = repo.file_exists().filename("config.json").send().await?;

    println!("config.json exists: {exists}");
    Ok(())
}

Download a file

use std::path::PathBuf;
use hf_hub::HFClient;

#[tokio::main]
async fn main() -> hf_hub::HFResult<()> {
    let client = HFClient::new()?;
    let repo = client.model("openai-community", "gpt2");

    let path = repo
        .download_file()
        .filename("config.json")
        .local_dir(PathBuf::from("/tmp/hf-downloads"))
        .send()
        .await?;

    println!("Downloaded to: {}", path.display());
    Ok(())
}

Upload a file

use hf_hub::HFClient;
use hf_hub::repository::AddSource;

#[tokio::main]
async fn main() -> hf_hub::HFResult<()> {
    let client = HFClient::new()?;
    let repo = client.model("your-username", "your-repo");

    let commit = repo
        .upload_file()
        .source(AddSource::Bytes(b"Hello, world!".to_vec().into()))
        .path_in_repo("greeting.txt")
        .commit_message("Add greeting file")
        .send()
        .await?;

    println!("Committed: {:?}", commit.commit_oid);
    Ok(())
}

Create a repository

use hf_hub::{HFClient, RepoTypeDataset};

#[tokio::main]
async fn main() -> hf_hub::HFResult<()> {
    let client = HFClient::new()?;

    let url = client
        .create_repository()
        .repo_type(RepoTypeDataset)
        .repo_id("your-username/new-model")
        .private(true)
        .exist_ok(true)
        .send()
        .await?;

    println!("Repository URL: {}", url.url);
    Ok(())
}

Authentication and configuration

hf-hub does not read environment variables. HFClient::new() uses the public Hub endpoint without authentication and caches files in .cache/huggingface/hub relative to the current working directory. Configure a token, endpoint, or cache location explicitly with HFClient::builder():

use hf_hub::HFClient;

let client = HFClient::builder()
    .token("hf_xxx")
    .endpoint("https://huggingface.co")
    .cache_dir("/tmp/hf-cache")
    .build()?;
# Ok::<(), hf_hub::HFError>(())

The hfrs CLI continues to support its existing environment-based configuration.

Error Handling

All fallible operations return Result<T, HFError>. The HFError enum provides structured variants for common failure modes:

• HFError::AuthRequired — 401 response, token is missing or invalid
• HFError::RepoNotFound — repository does not exist or is inaccessible
• HFError::BucketNotFound — bucket does not exist or is inaccessible
• HFError::EntryNotFound — file or path does not exist in the repository or bucket
• HFError::RevisionNotFound — branch, tag, or commit does not exist
• HFError::Forbidden — 403 response, insufficient permissions
• HFError::Conflict — 409 response, resource already exists or conflicts
• HFError::RateLimited — 429 response, too many requests
• HFError::Http — other HTTP errors with status code, URL, and response body

WebAssembly support

hf-hub compiles for wasm32-unknown-unknown. On wasm the API surface is the same call shape as native — client.model(owner, name).download_file_stream()…send().await — but only the streaming download path is wired up; methods that touch the filesystem (download_file, snapshot_download, upload_file, the cache and buckets modules, the blocking wrappers) are gated behind #[cfg(not(target_family = "wasm"))]. Pure-HTTP modules (repository, spaces, users) and HTTP-only methods on HFRepository (exists, info, list_*, etc.) are exposed on both targets.

Verify locally with ./scripts/verify_wasm.sh. CI runs the same check in the wasm job of .github/workflows/rust.yml. The wasm/smoke/ crate is a tiny wasm-bindgen library that exercises the wasm-safe surface end-to-end (see wasm/smoke/src/lib.rs).

When modifying client, error, retry, xet, or repository/download.rs, keep the wasm build green — reqwest's wasm backend has a reduced API (no is_connect, no redirect() policy) and its streams are !Send, and filesystem APIs must stay behind #[cfg(not(target_family = "wasm"))] gates.

License

Apache-2.0