swift-huggingface release notes / what's new

Hugging Face has announced the release of swift-huggingface, a new Swift package providing a complete client for the Hugging Face Hub. This library addresses critical reliability and developer experience gaps in the Swift ecosystem, specifically regarding large model downloads, cache synchronization with Python, and authentication flexibility.

Reliable Model Downloads and Resume Support

swift-huggingface replaces previous unreliable download mechanisms with a robust system built on URLSession download tasks. It provides explicit progress tracking and the ability to resume interrupted downloads, which is essential for the multi-gigabyte files common in machine learning.

Key download capabilities include:

  • Resume Support: The resumeDownloadFile method allows developers to pick up downloads from where they left off using saved resume data.
  • Snapshot Downloads: The downloadSnapshot function manages entire model repositories, tracking metadata to ensure only changed files are downloaded in subsequent calls.
  • Filtered Downloads: Users can specify patterns (e.g., *.safetensors, *.json) to download only the necessary files from a repository.

Python-Compatible Cache Structure

To eliminate redundant downloads, swift-huggingface implements a cache structure compatible with the Python huggingface_hub library. This allows Swift applications to share models already downloaded via the Python CLI or transformers library.

The cache utilizes content-addressed storage where files are stored by their ETag in a blobs/ directory. Snapshot directories use symlinks to these blobs to minimize disk usage. The library follows standard environment variable conventions for cache location, checking HF_HUB_CACHE, HF_HOME, and defaulting to ~/.cache/huggingface/hub. To prevent race conditions during multi-process access, the library employs flock(2) file locking.

Flexible Authentication and OAuth 2.0

Authentication is managed through a TokenProvider pattern, making the source of credentials explicit. The library supports several authentication flows:

  • Auto-detection: Automatically finds tokens in environment variables (HF_TOKEN, HUGGING_FACE_HUB_TOKEN), token files, or standard HF CLI locations.
  • Static Tokens: Explicitly provided tokens for CI/CD environments.
  • Keychain Integration: Secure storage for production apps via the system Keychain.
  • OAuth 2.0: A complete implementation for user-facing applications, including a HuggingFaceAuthenticationManager that handles system browser sign-in, token storage in Keychain, and automatic token refresh.

Comprehensive Hub and Inference API Coverage

Beyond file operations, swift-huggingface provides a full client for interacting with the Hugging Face Hub and Inference Providers:

  • Hub API: Support for listing and managing models, datasets, spaces, collections, and discussions.
  • Inference Client: The InferenceClient allows apps to access hundreds of models via Hugging Face Inference Providers, including capabilities like textToImage for generating images from text prompts.

Future Roadmap and Integration

Integration with swift-transformers is currently in progress via a pull request to replace the existing HubApi implementation. This update will extend the reliability of swift-huggingface to users of mlx-swift-lm and other ecosystem libraries. Additionally, Hugging Face is developing support for the Xet storage backend, which will introduce chunk-based deduplication to further accelerate downloads for large models.

Sources