HuggingFace Hub — complete API client for the HF platform.
The Hub is the central platform for sharing ML models, datasets, and Spaces. This module provides a unified facade over all Hub services organized by category:
Service categories
| Category | Module(s) | Functions |
|---|---|---|
| Authentication | Auth | who_am_i/1 |
| Repositories | Repos, Commits, Files, Snapshots, Tags | create, delete, upload, download |
| Models | Models | list_models, model_info |
| Datasets | Datasets, DatasetViewer | list, info, rows, search |
| Spaces | Spaces | runtime, secrets, hardware |
| Discovery | Search, Collections, Papers | search, trending |
| Collaboration | Discussions, Webhooks | PRs, comments, events |
| Storage | Buckets, Cache, FileSystem | S3-like, hf:// URIs |
| Compute | Jobs, AutoTrain | GPU workloads, training |
| Deployment | Endpoints | managed inference |
| Enterprise | Organizations, GatedRepos, OAuth | access control |
| Evaluation | Evaluate, Leaderboards | metrics, benchmarks |
| Community | Users | profiles, followers |
| Metadata | Metadata | model cards |
Example
# Search models
HuggingfaceClient.Hub.list_models(
task: "text-generation",
sort: "downloads",
limit: 10,
access_token: "hf_..."
)
|> Enum.each(fn m -> IO.puts(m["id"]) end)
# Upload a file
{:ok, _} = HuggingfaceClient.Hub.upload_file("my-org/my-model",
path: "README.md",
content: "# My Model",
access_token: "hf_..."
)
# Run a GPU job
{:ok, job} = HuggingfaceClient.Hub.run_job(
image: "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
command: ["python", "train.py"],
flavor: "a10g-small",
access_token: "hf_..."
)Summary
Functions
Accepts a gated repo request.
Adds item to a collection.
Adds a Space secret.
Adds a Space environment variable.
Returns audit logs for an organization.
Checks if a token has access to a repository.
Cancels an AutoTrain project.
Creates an AutoTrain project.
Lists AutoTrain projects.
Gets AutoTrain project status.
Batch upload/delete bucket files.
Gets bucket info.
Cancels a gated repo request.
Cancels a job.
Changes discussion status.
Comments on a discussion.
Computes a metric.
Computes multiple metrics.
Copies files between hf:// locations.
Creates a branch.
Creates a bucket.
Creates a collection.
Creates a discussion.
Creates an inference endpoint.
Creates a pull request.
Creates a new repository.
Creates a scheduled job.
Creates a tag.
Creates a webhook.
Gets detailed info about a dataset.
Returns all dataset tags.
Lists dataset configs.
Returns feature schema.
Returns first rows of a split.
Returns dataset info.
Checks if a dataset is in the Dataset Viewer.
Returns Parquet file URLs.
Returns paginated rows.
Searches dataset rows.
Returns dataset size.
Lists dataset splits.
Returns column statistics.
Default cache directory.
Deletes a branch.
Deletes a bucket.
Deletes all cached files for a repo.
Deletes a cached revision.
Deletes a collection.
Deletes item from a collection.
Deletes a file.
Deletes multiple files.
Deletes an inference endpoint.
Deletes a repository.
Deletes a scheduled job.
Deletes a Space secret.
Deletes a Space environment variable.
Deletes a tag.
Deletes a webhook.
Downloads a file's content.
Builds a DPO alignment configuration.
Duplicates a Space.
Edits a comment.
Evaluates a model on a dataset.
Exports specific entries as a DDUF file.
Exports a model folder as a DDUF file.
Streams job logs.
Streams job metrics.
Checks if a file exists.
Builds a full fine-tuning configuration.
Gets authenticated user info.
Downloads a bucket file.
Gets a collection.
Gets a discussion.
Gets an inference endpoint.
Gets a leaderboard.
Gets model card metadata.
Gets repository settings.
Gets Space runtime info.
Gets Space environment variables.
Gets a webhook.
Grants repo access.
Checks if user has at least a given role.
Downloads a file to the local HF cache and returns the path.
Returns the download URL for a file.
Hides a comment.
Gets job status.
Invites an org member.
Likes a repository on the Hub.
Lists accepted gated repo requests.
Lists bucket files.
Lists buckets.
Lists collections.
Lists commits for a repository.
Lists datasets with full filter support (lazy stream).
Lists discussions and PRs.
Lists files in a repository.
Lists inference endpoints.
Lists available hardware flavors.
Lists jobs.
Lists leaderboards.
Lists repositories liked by a user.
Lists available metrics.
Lists models with full filter support (lazy stream).
Lists orgs for the authenticated user.
Lists org members.
Lists papers.
Lists pending gated repo requests.
Lists rejected gated repo requests.
Lists all branches and tags for a repository.
Lists scheduled jobs.
Gets logs from a Space.
Lists Space secrets (keys only).
Lists spaces (lazy stream).
Lists a user's followers.
Lists users that a user follows.
Lists webhooks.
Downloads and opens a DDUF file from the Hub.
Downloads a model from the Hub (equivalent to from_pretrained).
Builds a LoRA fine-tuning configuration.
Merges a pull request.
Gets model benchmarks.
Gets detailed info about a model.
Returns all model tags.
Renames a bucket.
Moves or renames a repository.
Returns user's role in an organization.
OAuth callback handler.
OAuth login URL.
Returns Open LLM Leaderboard results.
Gets org info.
Gets paper info.
Parses safetensors metadata from a model repo.
Pauses an inference endpoint.
Pauses a Space.
Pushes eval results.
Pushes a model card to the Hub.
Pushes a model (weights + config) to a Hub repo.
Reads a DDUF file.
Reads a model card.
Rejects a gated repo request.
Removes an org member.
Renames a discussion.
Checks if a repository exists.
Gets papers associated with a repo.
Requests hardware upgrade.
Restarts a Space.
Resumes an inference endpoint.
Revokes repo access.
Runs a Docker job on HF infrastructure.
Runs a UV Python script.
Scales endpoint to zero.
Scans the local HF cache.
Searches datasets.
Full-text search across Hub content.
Searches models with full filter support.
Searches papers.
Searches Spaces.
Sets sleep time.
Downloads an entire repository to the local cache.
Enables/disables dev mode.
Gets info about a Space.
Streams audit log entries for an organization.
Submits to a leaderboard.
Squashes all commits in a branch into one.
Tags a specific commit.
Returns a pre-built fine-tuning recipe.
Returns trending models.
Returns trending Spaces.
Unlikes a repository on the Hub.
Updates a collection.
Updates a collection item (position, note).
Updates an inference endpoint.
Updates repo metadata.
Updates repository settings (private, gated, etc.).
Updates a webhook.
Uploads a file to a bucket.
Uploads a single file.
Uploads multiple files in a single commit.
Uploads an entire local folder.
Gets a user's profile.
Waits for a job to finish.
Returns info about the authenticated user.
Functions
Accepts a gated repo request.
Adds item to a collection.
Adds a Space secret.
Adds a Space environment variable.
Returns audit logs for an organization.
Checks if a token has access to a repository.
Cancels an AutoTrain project.
@spec autotrain_create(any()) :: {:ok, term()} | {:error, Exception.t()}
Creates an AutoTrain project.
Lists AutoTrain projects.
Gets AutoTrain project status.
Batch upload/delete bucket files.
Gets bucket info.
Cancels a gated repo request.
Cancels a job.
Changes discussion status.
Comments on a discussion.
Computes a metric.
@spec compute_metrics(any()) :: {:ok, term()} | {:error, Exception.t()}
Computes multiple metrics.
@spec copy_files(any()) :: {:ok, term()} | {:error, Exception.t()}
Copies files between hf:// locations.
@spec create_branch(any(), any(), keyword()) :: {:ok, term()} | {:error, Exception.t()}
Creates a branch.
Creates a bucket.
@spec create_collection(any()) :: {:ok, term()} | {:error, Exception.t()}
Creates a collection.
@spec create_discussion( String.t(), keyword() ) :: {:ok, term()} | {:error, Exception.t()}
Creates a discussion.
@spec create_inference_endpoint(any()) :: {:ok, term()} | {:error, Exception.t()}
Creates an inference endpoint.
Creates a pull request.
Creates a new repository.
@spec create_scheduled_job(any()) :: {:ok, term()} | {:error, Exception.t()}
Creates a scheduled job.
Creates a tag.
@spec create_webhook(any()) :: {:ok, term()} | {:error, Exception.t()}
Creates a webhook.
Gets detailed info about a dataset.
Returns all dataset tags.
Lists dataset configs.
Returns feature schema.
Returns first rows of a split.
Returns dataset info.
@spec dataset_viewer_is_valid?( any(), keyword() ) :: {:ok, term()} | {:error, Exception.t()}
Checks if a dataset is in the Dataset Viewer.
Returns Parquet file URLs.
Returns paginated rows.
Searches dataset rows.
Returns dataset size.
Lists dataset splits.
Returns column statistics.
@spec default_cache_dir() :: String.t()
Default cache directory.
@spec delete_branch(any(), any(), keyword()) :: {:ok, term()} | {:error, Exception.t()}
Deletes a branch.
Deletes a bucket.
Deletes all cached files for a repo.
Deletes a cached revision.
Deletes a collection.
Deletes item from a collection.
Deletes a file.
Deletes multiple files.
Deletes an inference endpoint.
Deletes a repository.
Deletes a scheduled job.
Deletes a Space secret.
Deletes a Space environment variable.
Deletes a tag.
Deletes a webhook.
@spec download_file(String.t(), String.t(), keyword()) :: {:ok, binary()} | {:error, Exception.t()}
Downloads a file's content.
@spec dpo_config(any()) :: {:ok, term()} | {:error, Exception.t()}
Builds a DPO alignment configuration.
Duplicates a Space.
Edits a comment.
Evaluates a model on a dataset.
Exports specific entries as a DDUF file.
Exports a model folder as a DDUF file.
Streams job logs.
Streams job metrics.
@spec file_exists?(String.t(), String.t(), keyword()) :: {:ok, boolean()} | {:error, Exception.t()}
Checks if a file exists.
Builds a full fine-tuning configuration.
@spec get_authenticated_user(any()) :: {:ok, term()} | {:error, Exception.t()}
Gets authenticated user info.
Downloads a bucket file.
Gets a collection.
Gets a discussion.
Gets an inference endpoint.
Gets a leaderboard.
Gets model card metadata.
Gets repository settings.
Gets Space runtime info.
Gets Space environment variables.
Gets a webhook.
Grants repo access.
Checks if user has at least a given role.
Downloads a file to the local HF cache and returns the path.
Returns the download URL for a file.
Hides a comment.
Gets job status.
Invites an org member.
Likes a repository on the Hub.
Lists accepted gated repo requests.
Lists bucket files.
@spec list_buckets(any()) :: {:ok, term()} | {:error, Exception.t()}
Lists buckets.
@spec list_collections(any()) :: {:ok, term()} | {:error, Exception.t()}
Lists collections.
Lists commits for a repository.
@spec list_datasets(any()) :: Enumerable.t()
Lists datasets with full filter support (lazy stream).
Lists discussions and PRs.
Lists files in a repository.
@spec list_inference_endpoints(any()) :: {:ok, term()} | {:error, Exception.t()}
Lists inference endpoints.
Lists available hardware flavors.
Lists jobs.
@spec list_leaderboards(any()) :: {:ok, term()} | {:error, Exception.t()}
Lists leaderboards.
@spec list_liked_repos(any()) :: {:ok, term()} | {:error, Exception.t()}
Lists repositories liked by a user.
@spec list_metrics(any()) :: {:ok, term()} | {:error, Exception.t()}
Lists available metrics.
@spec list_models(any()) :: Enumerable.t()
Lists models with full filter support (lazy stream).
@spec list_my_orgs(any()) :: {:ok, term()} | {:error, Exception.t()}
Lists orgs for the authenticated user.
Lists org members.
@spec list_papers(any()) :: {:ok, term()} | {:error, Exception.t()}
Lists papers.
Lists pending gated repo requests.
Lists rejected gated repo requests.
Lists all branches and tags for a repository.
Lists scheduled jobs.
Gets logs from a Space.
Lists Space secrets (keys only).
@spec list_spaces(any()) :: Enumerable.t()
Lists spaces (lazy stream).
Lists a user's followers.
Lists users that a user follows.
@spec list_webhooks(any()) :: {:ok, term()} | {:error, Exception.t()}
Lists webhooks.
Downloads and opens a DDUF file from the Hub.
@spec load_from_hub(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
Downloads a model from the Hub (equivalent to from_pretrained).
@spec lora_config(any()) :: {:ok, term()} | {:error, Exception.t()}
Builds a LoRA fine-tuning configuration.
Merges a pull request.
Gets model benchmarks.
Gets detailed info about a model.
@spec model_tags(any()) :: {:ok, term()} | {:error, Exception.t()}
Returns all model tags.
@spec move_bucket(any()) :: {:ok, term()} | {:error, Exception.t()}
Renames a bucket.
@spec move_repo(any()) :: {:ok, term()} | {:error, Exception.t()}
Moves or renames a repository.
Returns user's role in an organization.
OAuth callback handler.
OAuth login URL.
Returns Open LLM Leaderboard results.
Gets org info.
Gets paper info.
Parses safetensors metadata from a model repo.
Pauses an inference endpoint.
Pauses a Space.
Pushes eval results.
@spec push_model_card(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
Pushes a model card to the Hub.
@spec push_to_hub(any(), any(), any()) :: {:ok, term()} | {:error, Exception.t()}
Pushes a model (weights + config) to a Hub repo.
@spec read_dduf_file(any()) :: {:ok, term()} | {:error, Exception.t()}
Reads a DDUF file.
Reads a model card.
Rejects a gated repo request.
Removes an org member.
Renames a discussion.
@spec repo_exists?( String.t(), keyword() ) :: {:ok, boolean()} | {:error, Exception.t()}
Checks if a repository exists.
Gets papers associated with a repo.
Requests hardware upgrade.
Restarts a Space.
Resumes an inference endpoint.
Revokes repo access.
@spec run_job(any()) :: {:ok, term()} | {:error, Exception.t()}
Runs a Docker job on HF infrastructure.
Runs a UV Python script.
Scales endpoint to zero.
@spec scan_cache(any()) :: {:ok, term()} | {:error, Exception.t()}
Scans the local HF cache.
@spec search_datasets(any()) :: Enumerable.t()
Searches datasets.
Full-text search across Hub content.
@spec search_models(any()) :: Enumerable.t()
Searches models with full filter support.
@spec search_papers(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
Searches papers.
@spec search_spaces(any()) :: Enumerable.t()
Searches Spaces.
Sets sleep time.
Downloads an entire repository to the local cache.
Enables/disables dev mode.
Gets info about a Space.
Streams audit log entries for an organization.
@spec submit_to_leaderboard(any()) :: {:ok, term()} | {:error, Exception.t()}
Submits to a leaderboard.
Squashes all commits in a branch into one.
@spec tag_commit(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
Tags a specific commit.
Returns a pre-built fine-tuning recipe.
@spec trending_models(any()) :: {:ok, term()} | {:error, Exception.t()}
Returns trending models.
@spec trending_spaces(any()) :: {:ok, term()} | {:error, Exception.t()}
Returns trending Spaces.
Unlikes a repository on the Hub.
Updates a collection.
Updates a collection item (position, note).
Updates an inference endpoint.
Updates repo metadata.
Updates repository settings (private, gated, etc.).
Updates a webhook.
Uploads a file to a bucket.
Uploads a single file.
Uploads multiple files in a single commit.
Uploads an entire local folder.
Gets a user's profile.
Waits for a job to finish.
@spec who_am_i(any()) :: {:ok, term()} | {:error, Exception.t()}
Returns info about the authenticated user.