Struct HFClient 

pub struct HFClient { /* private fields */ }

Async client for the Hugging Face Hub API.

HFClient wraps an Arc<HFClientInner> so it is cheap to clone — all clones share the same underlying HTTP connection pool, token, and configuration.

Creating a client

use hf_hub::HFClient;

// Reads token and settings from the environment (HF_TOKEN, HF_ENDPOINT, …).
let client = HFClient::new()?;

// Or configure explicitly:
let client = HFClient::builder().token("hf_…").endpoint("https://huggingface.co").build()?;

Implementations

impl HFClient

pub fn new() -> HFResult<Self>

Creates a client with default settings, reading the token and endpoint from the environment. Equivalent to HFClient::builder().build().

Errors

Fails if the resolved endpoint URL is invalid or the HTTP client cannot be built.

pub fn builder() -> HFClientBuilder

Returns an HFClientBuilder for fine-grained configuration.

pub fn endpoint(&self) -> &str

Hub base URL this client targets, with any trailing slash trimmed.

Resolved at build time from HFClientBuilder::endpoint → HF_ENDPOINT → the default (https://huggingface.co).

pub fn cache_dir(&self) -> &Path

Local cache directory used for downloaded files.

Resolved at build time from HFClientBuilder::cache_dir → HF_HUB_CACHE → $HF_HOME/hub → ~/.cache/huggingface/hub. Returned even when caching is disabled — see cache_enabled to check that.

pub fn cache_enabled(&self) -> bool

Whether the local file cache is enabled. Set via HFClientBuilder::cache_enabled; defaults to true.

impl HFClient

pub fn bucket( &self, owner: impl Into<String>, name: impl Into<String>, ) -> HFBucket

Create an HFBucket handle for a bucket.

The returned handle is cheap to clone and can be reused across multiple bucket-scoped operations.

pub fn create_bucket<'f1, 'f2, 'f3>( &'f1 self, ) -> HFClientCreateBucketBuilder<'f1, 'f2, 'f3>

Create a new bucket on the Hub. Endpoint: POST /api/buckets/{namespace}/{name}.

When exist_ok is true, an existing bucket is treated as success and a BucketUrl is synthesized locally.

Parameters

• namespace (required): namespace (user or organization) that owns the bucket.
• name (required): bucket name within the namespace.
• private (default false): whether the bucket should be private.
• resource_group_id: enterprise resource group ID.
• exist_ok (default false): if true, do not error when the bucket already exists.

pub fn delete_bucket<'f1, 'f2>( &'f1 self, ) -> HFClientDeleteBucketBuilder<'f1, 'f2>

Delete a bucket from the Hub. Endpoint: DELETE /api/buckets/{bucket_id}.

Parameters

• bucket_id (required): bucket ID in "owner/name" format.
• missing_ok (default false): if true, do not error when the bucket does not exist.

pub fn list_buckets<'f1>(&'f1 self) -> HFClientListBucketsBuilder<'f1>

List buckets in a namespace.

Streams bucket metadata for all buckets owned by the given user or organization.

Endpoint: GET /api/buckets/{namespace} (paginated).

Parameters

• namespace (required): user or organization namespace to list buckets for.

pub fn move_bucket<'f1, 'f2, 'f3>( &'f1 self, ) -> HFClientMoveBucketBuilder<'f1, 'f2, 'f3>

Move (rename) a bucket.

Endpoint: POST /api/repos/move with type: "bucket".

Parameters

• from_id (required): current bucket ID in "owner/name" format.
• to_id (required): new bucket ID in "owner/name" format.

impl HFClient

pub fn scan_cache<'f1>(&'f1 self) -> HFClientScanCacheBuilder<'f1>

Available on non-target_family=wasm only.

Scan the configured cache directory and return a summary of all cached repositories, revisions, and files.

If the cache directory does not exist, returns an HFCacheInfo with no repos and zero size — not an error. Unreadable blobs and dangling snapshot pointers are reported via HFCacheInfo::warnings rather than failing the scan.

impl HFClient

pub fn repository<T: RepoType>( &self, repo_type: T, owner: impl Into<String>, name: impl Into<String>, ) -> HFRepository<T>

Create an HFRepository handle for any repo kind via a turbofished generic.

Equivalent to the typed shortcuts (model, dataset, space, kernel) but useful when the kind is expressed by an external type parameter or a match arm — for example, dispatching from a CLI flag:

let repo = client.repository(RepoTypeDataset, "rajpurkar", "squad");

pub fn model( &self, owner: impl Into<String>, name: impl Into<String>, ) -> HFRepository<RepoTypeModel>

Create an HFRepository handle for a model repository.

pub fn dataset( &self, owner: impl Into<String>, name: impl Into<String>, ) -> HFRepository<RepoTypeDataset>

Create an HFRepository handle for a dataset repository.

pub fn space( &self, owner: impl Into<String>, name: impl Into<String>, ) -> HFRepository<RepoTypeSpace>

Create an HFRepository handle for a Space repository.

pub fn kernel( &self, owner: impl Into<String>, name: impl Into<String>, ) -> HFRepository<RepoTypeKernel>

Create an HFRepository handle for a kernel repository.

impl HFClient

pub fn list_models<'f1>(&'f1 self) -> HFClientListModelsBuilder<'f1>

List models on the Hub. Endpoint: GET /api/models.

Returns a stream of ModelInfo entries. Pagination is automatic.

Parameters

• search: free-text query forwarded as the ?search= parameter. The Hub matches it substring-style against the model id and (when present) the model card description — it is not a tag filter.
• author: namespace owner to filter on, forwarded as ?author=. Pass a Hub user or organization name (e.g., "google", "meta-llama") — bare names, not paths.
• filter: a single Hub tag value forwarded as ?filter=. Tags use the Hub’s namespaced format, e.g., "pytorch", "text-generation", "license:apache-2.0", "language:en", "dataset:wikipedia", "region:us". To combine tags, narrow the results client-side (only one filter value is sent).
• sort: API field name to sort by, forwarded as ?sort=. Common values are "downloads", "likes", "createdAt", "lastModified", and "trendingScore". Use the camelCase Hub field names (not Rust struct field names).
• pipeline_tag: pipeline-tag filter (e.g., "text-classification", "automatic-speech-recognition"), forwarded as ?pipeline_tag=. Same vocabulary as the pipeline_tag field on a model card.
• full: fetch the full model information including all fields.
• card_data: include the model card metadata in the response.
• fetch_config: include the model configuration in the response.
• limit: cap on the total number of items yielded by the stream. When less than 1000, also used as the server page size.

pub fn list_datasets<'f1>(&'f1 self) -> HFClientListDatasetsBuilder<'f1>

List datasets on the Hub. Endpoint: GET /api/datasets.

Returns a stream of DatasetInfo entries. Pagination is automatic.

Parameters

• search: free-text query forwarded as ?search=. The Hub matches it substring-style against the dataset id and card description — not a tag filter.
• author: namespace owner forwarded as ?author=. Pass a bare Hub user or organization name (e.g., "HuggingFaceH4", "allenai").
• filter: a single Hub tag value forwarded as ?filter=. Tags use the Hub’s namespaced format, e.g., "task_categories:text-classification", "language:en", "size_categories:10K<n<100K", "license:mit". To combine tags, narrow client-side — only one filter value is sent.
• sort: API field name to sort by, forwarded as ?sort=. Common values are "downloads", "likes", "createdAt", "lastModified", and "trendingScore" (Hub camelCase field names).
• full: fetch the full dataset information including all fields.
• limit: cap on the total number of items yielded by the stream. When less than 1000, also used as the server page size.

pub fn list_spaces<'f1>(&'f1 self) -> HFClientListSpacesBuilder<'f1>

List Spaces on the Hub. Endpoint: GET /api/spaces.

Returns a stream of SpaceInfo entries. Pagination is automatic.

Parameters

• search: free-text query forwarded as ?search=. The Hub matches it substring-style against the Space id and card description — not a tag filter.
• author: namespace owner forwarded as ?author=. Pass a bare Hub user or organization name (e.g., "openai", "stabilityai").
• filter: a single Hub tag value forwarded as ?filter=. Tags use the Hub’s namespaced format, e.g., "sdk:gradio", "sdk:streamlit", "sdk:docker", "language:en", "license:mit". To combine tags, narrow client-side — only one filter value is sent.
• sort: API field name to sort by, forwarded as ?sort=. Common values are "likes", "createdAt", "lastModified", and "trendingScore" (Hub camelCase field names).
• full: fetch the full Space information including all fields.
• limit: cap on the total number of items yielded by the stream. When less than 1000, also used as the server page size.

pub fn create_repository<'f1, 'f2, I1>( &'f1 self, ) -> HFClientCreateRepositoryBuilder<'f1, 'f2, I1>

where I1: RepoType,

Create a new repository. Endpoint: POST /api/repos/create.

The repo kind is picked at the call site by passing one of the four marker structs to repo_type — e.g., client.create_repository().repo_type(RepoTypeDataset)... to create a dataset. The body always includes the type field, matching the Hub’s per-kind defaults.

Parameters

• repo_id (required): repository ID in "owner/name" or "name" format.
• repo_type (required): the repo kind (RepoTypeModel, RepoTypeDataset, RepoTypeSpace, or RepoTypeKernel).
• private: whether the repository should be private.
• exist_ok (default false): if true, do not error when the repository already exists.
• space_sdk: SDK for a Space (e.g., "gradio", "streamlit", "docker"). Required when repo_type is RepoTypeSpace; ignored for other repo kinds.

pub fn delete_repository<'f1, 'f2, I1>( &'f1 self, ) -> HFClientDeleteRepositoryBuilder<'f1, 'f2, I1>

where I1: RepoType,

Delete a repository. Endpoint: DELETE /api/repos/delete.

The repo kind is picked at the call site by passing one of the four marker structs to repo_type — e.g., client.delete_repository().repo_type(RepoTypeSpace).... The body always includes the type field.

Parameters

• repo_id (required): repository ID in "owner/name" or "name" format.
• repo_type (required): the repo kind (RepoTypeModel, RepoTypeDataset, RepoTypeSpace, or RepoTypeKernel).
• missing_ok (default false): if true, do not error when the repository does not exist.

pub fn move_repository<'f1, 'f2, 'f3, I1>( &'f1 self, ) -> HFClientMoveRepositoryBuilder<'f1, 'f2, 'f3, I1>

where I1: RepoType,

Move (rename) a repository. Endpoint: POST /api/repos/move.

The repo kind is picked at the call site by passing one of the four marker structs to repo_type — e.g., client.move_repository().repo_type(RepoTypeModel).... The body always includes the type field.

Parameters

• from_id (required): current repository ID in "owner/name" format.
• to_id (required): new repository ID in "owner/name" format.
• repo_type (required): the repo kind (RepoTypeModel, RepoTypeDataset, RepoTypeSpace, or RepoTypeKernel).

impl HFClient

pub fn whoami<'f1>(&'f1 self) -> HFClientWhoamiBuilder<'f1>

Fetch the profile of the user that owns the current token.

Returns the authenticated User, including private fields like email and the caller’s orgs list. Fails with HFError::AuthRequired if no valid token is configured.

Endpoint: GET /api/whoami-v2.

pub fn user_overview<'f1, 'f2>( &'f1 self, ) -> HFClientUserOverviewBuilder<'f1, 'f2>

Fetch the public profile of a user by Hub handle.

Endpoint: GET /api/users/{username}/overview.

Parameters

• username (required): Hub handle (slug) of the user.

pub fn organization_overview<'f1, 'f2>( &'f1 self, ) -> HFClientOrganizationOverviewBuilder<'f1, 'f2>

Fetch the public profile of an organization by Hub handle.

Endpoint: GET /api/organizations/{organization}/overview.

Parameters

• organization (required): Hub handle (slug) of the organization.

pub fn list_user_followers<'f1>( &'f1 self, ) -> HFClientListUserFollowersBuilder<'f1>

Stream the followers of a user.

Endpoint: GET /api/users/{username}/followers.

Parameters

• username (required): Hub handle of the user.
• limit: cap on the total number of items yielded.

pub fn list_user_following<'f1>( &'f1 self, ) -> HFClientListUserFollowingBuilder<'f1>

Stream the users that a user is following.

Endpoint: GET /api/users/{username}/following.

Parameters

• username (required): Hub handle of the user.
• limit: cap on the total number of items yielded.

pub fn list_organization_members<'f1>( &'f1 self, ) -> HFClientListOrganizationMembersBuilder<'f1>

Stream the members of an organization.

Endpoint: GET /api/organizations/{organization}/members.

Parameters

• organization (required): Hub handle of the organization.
• limit: cap on the total number of items yielded.

Trait Implementations

impl Clone for HFClient

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HFClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.