Introducing swift-huggingface: The Complete Swift Client for Hugging Face

Introducing swift-huggingface: The Complete Swift Client for Hugging Face

Today, we're announcing swift-huggingface, a new Swift package that provides a complete client for the Hugging Face Hub. You can start using it today as a standalone package, and it will soon integrate into swift-transformers as a replacement for its current HubApi implementation.

When we released swift-transformers 1.0 earlier this year, we heard loud and clear from the community:

Downloads were slow and unreliable. Large model files (often several gigabytes) would fail partway through with no way to resume. Developers resorted to manually downloading models and bundling them with their apps — defeating the purpose of dynamic model loading.

No shared cache with the Python ecosystem. The Python transformers library stores models in ~/.cache/huggingface/hub. Swift apps downloaded to a different location with a different structure. If you'd already downloaded a model using the Python CLI, you'd download it again for your Swift app.

Authentication is confusing. Where should tokens come from? Environment variables? Files? Keychain? The answer is, "It depends", and the existing implementation didn't make the options clear.

swift-huggingface is a ground-up rewrite focused on reliability and developer experience. It provides:

• Complete Hub API coverage — models, datasets, spaces, collections, discussions, and more
• Robust file operations — progress tracking, resume support, and proper error handling
• Python-compatible cache — share downloaded models between Swift and Python clients
• Flexible authentication — a TokenProvider pattern that makes credential sources explicit
• OAuth support — first-class support for user-facing apps that need to authenticate users
• Xet storage backend support (Coming soon!) — chunk-based deduplication for significantly faster downloads

Let's look at some examples.

One of the biggest improvements is how authentication works. The TokenProvider pattern makes it explicit where credentials come from:

import HuggingFace
// For development: auto-detect from environment and standard locations
// Checks HF_TOKEN, HUGGING_FACE_HUB_TOKEN, ~/.cache/huggingface/token, etc.
let client = HubClient.default
// For CI/CD: explicit token
let client = HubClient(tokenProvider: .static("hf_xxx"))
// For production apps: read from Keychain
let client = HubClient(tokenProvider: .keychain(service: "com.myapp", account: "hf_token"))

The auto-detection follows the same conventions as the Python huggingface_hub library. This means if you've already logged in with hf auth login, swift-huggingface will automatically find and use that token.

Building an app where users sign in with their Hugging Face account? swift-huggingface includes a complete OAuth 2.0 implementation. The OAuth manager handles token storage in Keychain, automatic refresh, and secure sign-out. No more manual token management.

Downloading large models is now straightforward with proper progress tracking and resume support. If a download is interrupted, you can resume it from where you left off. For downloading entire model repositories, downloadSnapshot handles everything, tracking metadata for each file so subsequent calls only download files that have changed.

Remember the second problem we mentioned? "No shared cache with the Python ecosystem." That's now solved. swift-huggingface implements a Python-compatible cache structure that allows seamless sharing between Swift and Python clients. This means you download once and use everywhere. Files are stored by their ETag in the blobs/ directory, and snapshot directories contain symlinks to blobs, minimizing disk usage.

The API is similar to the old HubApi, but the implementation is completely different — built on URLSession download tasks with proper delegate handling, resume data support, and metadata tracking.