Elixir client for HuggingFace Hub.
HfHub provides a comprehensive interface to the HuggingFace Hub API,
enabling Elixir applications to access models, datasets, and spaces.
Features
- Hub API Client — Fetch metadata for models, datasets, and spaces
- File Downloads — Stream files from HuggingFace repositories with resume support
- Smart Caching — Local file caching with LRU eviction and integrity checks
- Filesystem Utilities — Manage local HuggingFace cache directory structure
- Authentication — Token-based authentication for private repositories
Quick Start
# Get model information
{:ok, model_info} = HfHub.Api.model_info("bert-base-uncased")
# Download a model file
{:ok, path} = HfHub.Download.hf_hub_download(
repo_id: "bert-base-uncased",
filename: "config.json",
repo_type: :model
)
# Check cache
cached? = HfHub.Cache.cached?(
repo_id: "bert-base-uncased",
filename: "config.json"
)Configuration
Configure in config/config.exs:
config :hf_hub,
token: System.get_env("HF_TOKEN"),
cache_dir: Path.expand("~/.cache/huggingface"),
endpoint: "https://huggingface.co"Modules
HfHub.Api— Hub API client (models, datasets, spaces)HfHub.Download— File download with cachingHfHub.Cache— Cache management and statisticsHfHub.FS— Filesystem utilities for cacheHfHub.Auth— Authentication and authorizationHfHub.Hub— Bumblebee-compatible ETag-based cachingHfHub.Repository— Repository reference typesHfHub.RepoFiles— Repository file listing with ETags
Summary
Types
A repository reference (Bumblebee-compatible).
Functions
Alias for offline_mode?/0 for Python compatibility.
Check if offline mode is enabled.
Try to load a file from cache without network access.
Types
@type filename() :: String.t()
@type repo_id() :: String.t()
@type repo_type() :: :model | :dataset | :space
@type repository() :: HfHub.Repository.t()
A repository reference (Bumblebee-compatible).
Can be either:
{:hf, repository_id}- HuggingFace repository{:hf, repository_id, opts}- HuggingFace repository with options{:local, directory}- Local directory
@type revision() :: String.t()
Functions
See HfHub.Hub.file_url/3.
@spec is_offline_mode() :: boolean()
Alias for offline_mode?/0 for Python compatibility.
Deprecated: Use offline_mode?/0 instead.
@spec offline_mode?() :: boolean()
Check if offline mode is enabled.
Offline mode can be enabled via:
HF_HUB_OFFLINE=1environment variableApplication.put_env(:hf_hub, :offline, true)
When offline mode is enabled, no network requests are made and only cached files are used.
Examples
if HfHub.offline_mode?() do
IO.puts("Running in offline mode")
end@spec try_to_load_from_cache(repo_id(), filename(), keyword()) :: {:ok, Path.t()} | {:error, :not_cached}
Try to load a file from cache without network access.
Returns {:ok, path} if the file exists in cache, {:error, :not_cached} otherwise.
Does not attempt any network requests, even if offline mode is not enabled.
This is useful when you want to check if a file is available locally before deciding whether to download it.
Arguments
repo_id- Repository ID (e.g., "bert-base-uncased")filename- Name of the file to look upopts- Options
Options
:revision- Git revision. Defaults to"main".:repo_type- Type of repository (:model,:dataset, or:space). Defaults to:model.
Examples
case HfHub.try_to_load_from_cache("bert-base-uncased", "config.json") do
{:ok, path} ->
# File is cached, use it
File.read!(path)
{:error, :not_cached} ->
# File not cached, need to download
{:ok, path} = HfHub.Download.hf_hub_download(
repo_id: "bert-base-uncased",
filename: "config.json"
)
File.read!(path)
end