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

[Hugging Face](https://yomu.fyi/company/hugging-face) · Mattt · Dec 5, 2025

**Type:** Announcement

## Summary

Hugging Face released swift-huggingface, a dedicated Swift package offering complete Hub API integration, reliable file downloads, and inference provider access. The library addresses previous limitations in swift-transformers 1.0, where interrupted multi-gigabyte model downloads could not resume and cache structures differed from Python. To resolve cache duplication, swift-huggingface implements a Python-compatible content-addressed storage layout using symlinks and flock file locking. Authentication is standardized through a TokenProvider pattern supporting auto-detection, Keychain integration, static CI/CD tokens, and OAuth 2.0 sign-in with automatic token refresh. The package also provides URLSession-backed snapshot downloads with granular progress tracking and will soon replace the HubApi implementation inside swift-transformers.

## Context

swift-transformers 1.0 faced community issues with slow, non-resumable downloads of multi-gigabyte models, prompting developers to bundle models manually. Additionally, Swift apps used a distinct cache structure from Python's ~/.cache/huggingface/hub, resulting in duplicate downloads across ecosystems, while authentication token sourcing was ambiguous across environment variables, files, and Keychain.

## Approach / What changed

swift-huggingface was built as a standalone Swift package providing complete Hugging Face Hub API coverage, URLSession-based downloads with resume support, flock-based file locking, and Python-compatible content-addressed caching. It introduces a TokenProvider pattern with auto-detection, explicit static and Keychain options, OAuth 2.0 support via HuggingFaceAuthenticationManager, and an InferenceClient for ML inference providers.

## Takeaways

- swift-huggingface shares a content-addressed cache structure with Python's huggingface\_hub using blobs, refs, snapshots symlinks, and flock(2) locking to prevent duplicate downloads and race conditions.
- The TokenProvider architecture resolves credential ambiguity by supporting environment variable auto-detection, static tokens, Keychain storage, and an OAuth 2.0 flow that automates token refresh.
- Model downloads leverage URLSession download tasks to provide accurate per-file progress tracking, resumable downloads for interrupted transfers, and selective snapshot retrieval.

**Tags:** [Authentication](https://yomu.fyi/topic/authentication), [Caching](https://yomu.fyi/topic/caching), [Developer Experience](https://yomu.fyi/topic/developer-experience), [Machine Learning](https://yomu.fyi/topic/machine-learning), [Open Source](https://yomu.fyi/topic/open-source)

[Read original post](https://huggingface.co/blog/swift-huggingface)