{ "@context": "https://schema.org", "@id": "https://aggr.aymericbeaumet.com/items/huggingface-co/2025-12-05-introducing-swift-huggingface-the-complete-swift-client-for/#webpage", "@type": [ "WebPage", "ArchiveComponent" ], "articleBody": "Today, we're announcing [swift-huggingface](https://github.com/huggingface/swift-huggingface), a new Swift package that provides a complete client for the Hugging Face Hub.\n\nYou 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.\n\n## The Problem\n\nWhen we released [swift-transformers 1.0](https://huggingface.co/blog/swift-transformers) earlier this year, we heard loud and clear from the community:\n\n- **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.\n- **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.\n- **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.\n\n## Introducing swift-huggingface\n\nswift-huggingface is a ground-up rewrite focused on reliability and developer experience. It provides:\n\n- **Complete Hub API coverage** — models, datasets, spaces, collections, discussions, and more\n- **Robust file operations** — progress tracking, resume support, and proper error handling\n- **Python-compatible cache** — share downloaded models between Swift and Python clients\n- **Flexible authentication** — a `TokenProvider` pattern that makes credential sources explicit\n- **OAuth support** — first-class support for user-facing apps that need to authenticate users\n- **Xet storage backend support** *(Coming soon!)* — chunk-based deduplication for significantly faster downloads\n\nLet's look at some examples.\n\n* * *\n\n## Flexible Authentication with TokenProvider\n\nOne of the biggest improvements is how authentication works. The `TokenProvider` pattern makes it explicit where credentials come from:\n\n```swift\nimport HuggingFace\n\n// For development: auto-detect from environment and standard locations\n// Checks HF_TOKEN, HUGGING_FACE_HUB_TOKEN, ~/.cache/huggingface/token, etc.\nlet client = HubClient.default\n\n// For CI/CD: explicit token\nlet client = HubClient(tokenProvider: .static(\"hf_xxx\"))\n\n// For production apps: read from Keychain\nlet client = HubClient(tokenProvider: .keychain(service: \"com.myapp\", account: \"hf_token\"))\n```\n\nThe auto-detection follows the same conventions as the Python `huggingface_hub` library:\n\n1. `HF_TOKEN` environment variable\n2. `HUGGING_FACE_HUB_TOKEN` environment variable\n3. `HF_TOKEN_PATH` environment variable (path to token file)\n4. `$HF_HOME/token` file\n5. `~/.cache/huggingface/token` (standard HF CLI location)\n6. `~/.huggingface/token` (fallback location)\n\nThis means if you've already logged in with `hf auth login`, swift-huggingface will automatically find and use that token.\n\n## OAuth for User-Facing Apps\n\nBuilding an app where users sign in with their Hugging Face account? swift-huggingface includes a complete OAuth 2.0 implementation:\n\n```swift\nimport HuggingFace\n\n// Create authentication manager\nlet authManager = try HuggingFaceAuthenticationManager(\n clientID: \"your_client_id\",\n redirectURL: URL(string: \"yourapp://oauth/callback\")!,\n scope: [.openid, .profile, .email],\n keychainService: \"com.yourapp.huggingface\",\n keychainAccount: \"user_token\"\n)\n\n// Sign in user (presents system browser)\ntry await authManager.signIn()\n\n// Use with Hub client\nlet client = HubClient(tokenProvider: .oauth(manager: authManager))\n\n// Tokens are automatically refreshed when needed\nlet userInfo = try await client.whoami()\nprint(\"Signed in as: \\(userInfo.name)\")\n```\n\nThe OAuth manager handles token storage in Keychain, automatic refresh, and secure sign-out. No more manual token management.\n\n## Reliable Downloads\n\nDownloading large models is now straightforward with proper progress tracking and resume support:\n\n```swift\n// Download with progress tracking\nlet progress = Progress(totalUnitCount: 0)\n\nTask {\n for await _ in progress.publisher(for: \\.fractionCompleted).values {\n print(\"Download: \\(Int(progress.fractionCompleted * 100))%\")\n }\n}\n\nlet fileURL = try await client.downloadFile(\n at: \"model.safetensors\",\n from: \"microsoft/phi-2\",\n to: destinationURL,\n progress: progress\n)\n```\n\nIf a download is interrupted, you can resume it:\n\n```swift\n// Resume from where you left off\nlet fileURL = try await client.resumeDownloadFile(\n resumeData: savedResumeData,\n to: destinationURL,\n progress: progress\n)\n```\n\nFor downloading entire model repositories, `downloadSnapshot` handles everything:\n\n```swift\nlet modelDir = try await client.downloadSnapshot(\n of: \"mlx-community/Llama-3.2-1B-Instruct-4bit\",\n to: cacheDirectory,\n matching: [\"*.safetensors\", \"*.json\"], // Only download what you need\n progressHandler: { progress in\n print(\"Downloaded \\(progress.completedUnitCount) of \\(progress.totalUnitCount) files\")\n }\n)\n```\n\nThe snapshot function tracks metadata for each file, so subsequent calls only download files that have changed.\n\n## Shared Cache with Python\n\nRemember the second problem we mentioned? *\"No shared cache with the Python ecosystem.\"* That's now solved.\n\nswift-huggingface implements a Python-compatible cache structure that allows seamless sharing between Swift and Python clients:\n\n```\n~/.cache/huggingface/hub/\n├── models--deepseek-ai--DeepSeek-V3.2/\n│ ├── blobs/\n│ │ └── # actual file content\n│ ├── refs/\n│ │ └── main # contains commit hash\n│ └── snapshots/\n│ └── /\n│ └── config.json # symlink → ../../blobs/\n```\n\nThis means:\n\n- **Download once, use everywhere.** If you've already downloaded a model with the `hf` CLI or the Python library, swift-huggingface will find it automatically.\n- **Content-addressed storage.** Files are stored by their ETag in the `blobs/` directory. If two revisions share the same file, it's only stored once.\n- **Symlinks for efficiency.** Snapshot directories contain symlinks to blobs, minimizing disk usage while maintaining a clean file structure.\n\nThe cache location follows the same environment variable conventions as Python:\n\n1. `HF_HUB_CACHE` environment variable\n2. `HF_HOME` environment variable + `/hub`\n3. `~/.cache/huggingface/hub` (default)\n\nYou can also use the cache directly:\n\n```swift\nlet cache = HubCache.default\n\n// Check if a file is already cached\nif let cachedPath = cache.cachedFilePath(\n repo: \"deepseek-ai/DeepSeek-V3.2\",\n kind: .model,\n revision: \"main\",\n filename: \"config.json\"\n) {\n let data = try Data(contentsOf: cachedPath)\n // Use cached file without any network request\n}\n```\n\nTo prevent race conditions when multiple processes access the same cache, swift-huggingface uses file locking ([`flock(2)`](https://man7.org/linux/man-pages/man2/flock.2.html)).\n\n## Before and After\n\nHere's what downloading a model snapshot looked like with the old `HubApi`:\n\n```swift\n// Before: HubApi in swift-transformers\nlet hub = HubApi()\nlet repo = Hub.Repo(id: \"mlx-community/Llama-3.2-1B-Instruct-4bit\")\n\n// No progress tracking, no resume, errors swallowed\nlet modelDir = try await hub.snapshot(\n from: repo,\n matching: [\"*.safetensors\", \"*.json\"]\n) { progress in\n // Progress object exists but wasn't always accurate\n print(progress.fractionCompleted)\n}\n```\n\nAnd here's the same operation with swift-huggingface:\n\n```swift\n// After: swift-huggingface\nlet client = HubClient.default\n\nlet modelDir = try await client.downloadSnapshot(\n of: \"mlx-community/Llama-3.2-1B-Instruct-4bit\",\n to: cacheDirectory,\n matching: [\"*.safetensors\", \"*.json\"],\n progressHandler: { progress in\n // Accurate progress per file\n print(\"\\(progress.completedUnitCount)/\\(progress.totalUnitCount) files\")\n }\n)\n```\n\nThe API is similar, but the implementation is completely different — built on `URLSession` download tasks with proper delegate handling, resume data support, and metadata tracking.\n\n## Beyond Downloads\n\nBut wait, there's more! swift-huggingface contains a complete Hub client:\n\n```swift\n// List trending models\nlet models = try await client.listModels(\n filter: \"library:mlx\",\n sort: \"trending\",\n limit: 10\n)\n\n// Get model details\nlet model = try await client.getModel(\"mlx-community/Llama-3.2-1B-Instruct-4bit\")\nprint(\"Downloads: \\(model.downloads ?? 0)\")\nprint(\"Likes: \\(model.likes ?? 0)\")\n\n// Work with collections\nlet collections = try await client.listCollections(owner: \"huggingface\", sort: \"trending\")\n\n// Manage discussions\nlet discussions = try await client.listDiscussions(kind: .model, \"username/my-model\")\n```\n\nAnd that's not all! swift-huggingface has everything you need to interact with [Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers/index), giving your app instant access to hundreds of machine learning models, powered by world-class inference providers:\n\n```swift\nimport HuggingFace\n\n// Create a client (uses auto-detected credentials from environment)\nlet client = InferenceClient.default\n\n// Generate images from a text prompt\nlet response = try await client.textToImage(\n model: \"black-forest-labs/FLUX.1-schnell\",\n prompt: \"A serene Japanese garden with cherry blossoms\",\n provider: .hfInference,\n width: 1024,\n height: 1024,\n numImages: 1,\n guidanceScale: 7.5,\n numInferenceSteps: 50,\n seed: 42\n)\n\n// Save the generated image\ntry response.image.write(to: URL(fileURLWithPath: \"generated.png\"))\n```\n\nCheck the [README](https://github.com/huggingface/swift-huggingface) for a full list of everything that's supported.\n\n## What's Next\n\nWe're actively working on two fronts:\n\n**Integration with swift-transformers.** We have a [pull request in progress](https://github.com/huggingface/swift-transformers/pull/297) to replace `HubApi` with swift-huggingface. This will bring reliable downloads to everyone using swift-transformers, [mlx-swift-lm](https://github.com/ml-explore/mlx-swift-lm), and the broader ecosystem. If you maintain a Swift-based library or app and want help adopting swift-huggingface, reach out — we're happy to help.\n\n**Faster downloads with Xet.** We're adding support for the [Xet storage backend](https://huggingface.co/docs/hub/storage-backends), which enables chunk-based deduplication and significantly faster downloads for large models. More on this soon.\n\n## Try It Out\n\nAdd swift-huggingface to your project:\n\n```swift\ndependencies: [\n .package(url: \"https://github.com/huggingface/swift-huggingface.git\", from: \"0.4.0\")\n]\n```\n\nWe'd love your feedback. If you've been frustrated with model downloads in Swift, give this a try and [let us know how it goes](https://github.com/huggingface/swift-huggingface/issues). Your experience reports will help us prioritize what to improve next.\n\n## Resources\n\n- [swift-huggingface on GitHub](https://github.com/huggingface/swift-huggingface)\n- [swift-transformers](https://github.com/huggingface/swift-transformers)\n- [mlx-swift-examples](https://github.com/ml-explore/mlx-swift-examples)\n- [AnyLanguageModel](https://github.com/mattt/AnyLanguageModel)\n\n* * *\n\n*Thanks to the swift-transformers community for the feedback that shaped this project, and to everyone who filed issues and shared their experiences. This is for you.* ❤️\n", "authors": [], "captured_at": "2026-10-04T12:50:30.804479567+00:00", "category": "ai", "content_html": "

Today, we're announcing swift-huggingface, a new Swift package that provides a complete client for the Hugging Face Hub.

\n

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.

\n

The Problem

\n

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

\n
    \n
  • 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.
    • \n
  • 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.
    • \n
  • 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.
    • \n
\n

Introducing swift-huggingface

\n

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

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

Let's look at some examples.

\n
\n

Flexible Authentication with TokenProvider

\n

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

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

The auto-detection follows the same conventions as the Python huggingface_hub library:

\n
    \n
  1. HF_TOKEN environment variable
    2. \n
  2. HUGGING_FACE_HUB_TOKEN environment variable
    3. \n
  3. HF_TOKEN_PATH environment variable (path to token file)
    4. \n
  4. $HF_HOME/token file
    5. \n
  5. ~/.cache/huggingface/token (standard HF CLI location)
    6. \n
  6. ~/.huggingface/token (fallback location)
    7. \n
\n

This means if you've already logged in with hf auth login, swift-huggingface will automatically find and use that token.

\n

OAuth for User-Facing Apps

\n

Building an app where users sign in with their Hugging Face account? swift-huggingface includes a complete OAuth 2.0 implementation:

\n
import HuggingFace\n\n// Create authentication manager\nlet authManager = try HuggingFaceAuthenticationManager(\n    clientID: "your_client_id",\n    redirectURL: URL(string: "yourapp://oauth/callback")!,\n    scope: [.openid, .profile, .email],\n    keychainService: "com.yourapp.huggingface",\n    keychainAccount: "user_token"\n)\n\n// Sign in user (presents system browser)\ntry await authManager.signIn()\n\n// Use with Hub client\nlet client = HubClient(tokenProvider: .oauth(manager: authManager))\n\n// Tokens are automatically refreshed when needed\nlet userInfo = try await client.whoami()\nprint("Signed in as: \\(userInfo.name)")\n
\n

The OAuth manager handles token storage in Keychain, automatic refresh, and secure sign-out. No more manual token management.

\n

Reliable Downloads

\n

Downloading large models is now straightforward with proper progress tracking and resume support:

\n
// Download with progress tracking\nlet progress = Progress(totalUnitCount: 0)\n\nTask {\n    for await _ in progress.publisher(for: \\.fractionCompleted).values {\n        print("Download: \\(Int(progress.fractionCompleted * 100))%")\n    }\n}\n\nlet fileURL = try await client.downloadFile(\n    at: "model.safetensors",\n    from: "microsoft/phi-2",\n    to: destinationURL,\n    progress: progress\n)\n
\n

If a download is interrupted, you can resume it:

\n
// Resume from where you left off\nlet fileURL = try await client.resumeDownloadFile(\n    resumeData: savedResumeData,\n    to: destinationURL,\n    progress: progress\n)\n
\n

For downloading entire model repositories, downloadSnapshot handles everything:

\n
let modelDir = try await client.downloadSnapshot(\n    of: "mlx-community/Llama-3.2-1B-Instruct-4bit",\n    to: cacheDirectory,\n    matching: ["*.safetensors", "*.json"],  // Only download what you need\n    progressHandler: { progress in\n        print("Downloaded \\(progress.completedUnitCount) of \\(progress.totalUnitCount) files")\n    }\n)\n
\n

The snapshot function tracks metadata for each file, so subsequent calls only download files that have changed.

\n

Shared Cache with Python

\n

Remember the second problem we mentioned? "No shared cache with the Python ecosystem." That's now solved.

\n

swift-huggingface implements a Python-compatible cache structure that allows seamless sharing between Swift and Python clients:

\n
~/.cache/huggingface/hub/\n├── models--deepseek-ai--DeepSeek-V3.2/\n│   ├── blobs/\n│   │   └── <etag>           # actual file content\n│   ├── refs/\n│   │   └── main             # contains commit hash\n│   └── snapshots/\n│       └── <commit_hash>/\n│           └── config.json  # symlink → ../../blobs/<etag>\n
\n

This means:

\n
    \n
  • Download once, use everywhere. If you've already downloaded a model with the hf CLI or the Python library, swift-huggingface will find it automatically.
    • \n
  • Content-addressed storage. Files are stored by their ETag in the blobs/ directory. If two revisions share the same file, it's only stored once.
    • \n
  • Symlinks for efficiency. Snapshot directories contain symlinks to blobs, minimizing disk usage while maintaining a clean file structure.
    • \n
\n

The cache location follows the same environment variable conventions as Python:

\n
    \n
  1. HF_HUB_CACHE environment variable
    2. \n
  2. HF_HOME environment variable + /hub
    3. \n
  3. ~/.cache/huggingface/hub (default)
    4. \n
\n

You can also use the cache directly:

\n
let cache = HubCache.default\n\n// Check if a file is already cached\nif let cachedPath = cache.cachedFilePath(\n    repo: "deepseek-ai/DeepSeek-V3.2",\n    kind: .model,\n    revision: "main",\n    filename: "config.json"\n) {\n    let data = try Data(contentsOf: cachedPath)\n    // Use cached file without any network request\n}\n
\n

To prevent race conditions when multiple processes access the same cache, swift-huggingface uses file locking (flock(2)).

\n

Before and After

\n

Here's what downloading a model snapshot looked like with the old HubApi:

\n
// Before: HubApi in swift-transformers\nlet hub = HubApi()\nlet repo = Hub.Repo(id: "mlx-community/Llama-3.2-1B-Instruct-4bit")\n\n// No progress tracking, no resume, errors swallowed\nlet modelDir = try await hub.snapshot(\n    from: repo,\n    matching: ["*.safetensors", "*.json"]\n) { progress in\n    // Progress object exists but wasn't always accurate\n    print(progress.fractionCompleted)\n}\n
\n

And here's the same operation with swift-huggingface:

\n
// After: swift-huggingface\nlet client = HubClient.default\n\nlet modelDir = try await client.downloadSnapshot(\n    of: "mlx-community/Llama-3.2-1B-Instruct-4bit",\n    to: cacheDirectory,\n    matching: ["*.safetensors", "*.json"],\n    progressHandler: { progress in\n        // Accurate progress per file\n        print("\\(progress.completedUnitCount)/\\(progress.totalUnitCount) files")\n    }\n)\n
\n

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

\n

Beyond Downloads

\n

But wait, there's more! swift-huggingface contains a complete Hub client:

\n
// List trending models\nlet models = try await client.listModels(\n    filter: "library:mlx",\n    sort: "trending",\n    limit: 10\n)\n\n// Get model details\nlet model = try await client.getModel("mlx-community/Llama-3.2-1B-Instruct-4bit")\nprint("Downloads: \\(model.downloads ?? 0)")\nprint("Likes: \\(model.likes ?? 0)")\n\n// Work with collections\nlet collections = try await client.listCollections(owner: "huggingface", sort: "trending")\n\n// Manage discussions\nlet discussions = try await client.listDiscussions(kind: .model, "username/my-model")\n
\n

And that's not all! swift-huggingface has everything you need to interact with Hugging Face Inference Providers, giving your app instant access to hundreds of machine learning models, powered by world-class inference providers:

\n
import HuggingFace\n\n// Create a client (uses auto-detected credentials from environment)\nlet client = InferenceClient.default\n\n// Generate images from a text prompt\nlet response = try await client.textToImage(\n    model: "black-forest-labs/FLUX.1-schnell",\n    prompt: "A serene Japanese garden with cherry blossoms",\n    provider: .hfInference,\n    width: 1024,\n    height: 1024,\n    numImages: 1,\n    guidanceScale: 7.5,\n    numInferenceSteps: 50,\n    seed: 42\n)\n\n// Save the generated image\ntry response.image.write(to: URL(fileURLWithPath: "generated.png"))\n
\n

Check the README for a full list of everything that's supported.

\n

What's Next

\n

We're actively working on two fronts:

\n

Integration with swift-transformers. We have a pull request in progress to replace HubApi with swift-huggingface. This will bring reliable downloads to everyone using swift-transformers, mlx-swift-lm, and the broader ecosystem. If you maintain a Swift-based library or app and want help adopting swift-huggingface, reach out — we're happy to help.

\n

Faster downloads with Xet. We're adding support for the Xet storage backend, which enables chunk-based deduplication and significantly faster downloads for large models. More on this soon.

\n

Try It Out

\n

Add swift-huggingface to your project:

\n
dependencies: [\n    .package(url: "https://github.com/huggingface/swift-huggingface.git", from: "0.4.0")\n]\n
\n

We'd love your feedback. If you've been frustrated with model downloads in Swift, give this a try and let us know how it goes. Your experience reports will help us prioritize what to improve next.

\n

Resources

\n\n
\n

Thanks to the swift-transformers community for the feedback that shaped this project, and to everyone who filed issues and shared their experiences. This is for you. ❤️

\n", "content_markdown": "Today, we're announcing [swift-huggingface](https://github.com/huggingface/swift-huggingface), a new Swift package that provides a complete client for the Hugging Face Hub.\n\nYou 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.\n\n## The Problem\n\nWhen we released [swift-transformers 1.0](https://huggingface.co/blog/swift-transformers) earlier this year, we heard loud and clear from the community:\n\n- **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.\n- **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.\n- **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.\n\n## Introducing swift-huggingface\n\nswift-huggingface is a ground-up rewrite focused on reliability and developer experience. It provides:\n\n- **Complete Hub API coverage** — models, datasets, spaces, collections, discussions, and more\n- **Robust file operations** — progress tracking, resume support, and proper error handling\n- **Python-compatible cache** — share downloaded models between Swift and Python clients\n- **Flexible authentication** — a `TokenProvider` pattern that makes credential sources explicit\n- **OAuth support** — first-class support for user-facing apps that need to authenticate users\n- **Xet storage backend support** *(Coming soon!)* — chunk-based deduplication for significantly faster downloads\n\nLet's look at some examples.\n\n* * *\n\n## Flexible Authentication with TokenProvider\n\nOne of the biggest improvements is how authentication works. The `TokenProvider` pattern makes it explicit where credentials come from:\n\n```swift\nimport HuggingFace\n\n// For development: auto-detect from environment and standard locations\n// Checks HF_TOKEN, HUGGING_FACE_HUB_TOKEN, ~/.cache/huggingface/token, etc.\nlet client = HubClient.default\n\n// For CI/CD: explicit token\nlet client = HubClient(tokenProvider: .static(\"hf_xxx\"))\n\n// For production apps: read from Keychain\nlet client = HubClient(tokenProvider: .keychain(service: \"com.myapp\", account: \"hf_token\"))\n```\n\nThe auto-detection follows the same conventions as the Python `huggingface_hub` library:\n\n1. `HF_TOKEN` environment variable\n2. `HUGGING_FACE_HUB_TOKEN` environment variable\n3. `HF_TOKEN_PATH` environment variable (path to token file)\n4. `$HF_HOME/token` file\n5. `~/.cache/huggingface/token` (standard HF CLI location)\n6. `~/.huggingface/token` (fallback location)\n\nThis means if you've already logged in with `hf auth login`, swift-huggingface will automatically find and use that token.\n\n## OAuth for User-Facing Apps\n\nBuilding an app where users sign in with their Hugging Face account? swift-huggingface includes a complete OAuth 2.0 implementation:\n\n```swift\nimport HuggingFace\n\n// Create authentication manager\nlet authManager = try HuggingFaceAuthenticationManager(\n clientID: \"your_client_id\",\n redirectURL: URL(string: \"yourapp://oauth/callback\")!,\n scope: [.openid, .profile, .email],\n keychainService: \"com.yourapp.huggingface\",\n keychainAccount: \"user_token\"\n)\n\n// Sign in user (presents system browser)\ntry await authManager.signIn()\n\n// Use with Hub client\nlet client = HubClient(tokenProvider: .oauth(manager: authManager))\n\n// Tokens are automatically refreshed when needed\nlet userInfo = try await client.whoami()\nprint(\"Signed in as: \\(userInfo.name)\")\n```\n\nThe OAuth manager handles token storage in Keychain, automatic refresh, and secure sign-out. No more manual token management.\n\n## Reliable Downloads\n\nDownloading large models is now straightforward with proper progress tracking and resume support:\n\n```swift\n// Download with progress tracking\nlet progress = Progress(totalUnitCount: 0)\n\nTask {\n for await _ in progress.publisher(for: \\.fractionCompleted).values {\n print(\"Download: \\(Int(progress.fractionCompleted * 100))%\")\n }\n}\n\nlet fileURL = try await client.downloadFile(\n at: \"model.safetensors\",\n from: \"microsoft/phi-2\",\n to: destinationURL,\n progress: progress\n)\n```\n\nIf a download is interrupted, you can resume it:\n\n```swift\n// Resume from where you left off\nlet fileURL = try await client.resumeDownloadFile(\n resumeData: savedResumeData,\n to: destinationURL,\n progress: progress\n)\n```\n\nFor downloading entire model repositories, `downloadSnapshot` handles everything:\n\n```swift\nlet modelDir = try await client.downloadSnapshot(\n of: \"mlx-community/Llama-3.2-1B-Instruct-4bit\",\n to: cacheDirectory,\n matching: [\"*.safetensors\", \"*.json\"], // Only download what you need\n progressHandler: { progress in\n print(\"Downloaded \\(progress.completedUnitCount) of \\(progress.totalUnitCount) files\")\n }\n)\n```\n\nThe snapshot function tracks metadata for each file, so subsequent calls only download files that have changed.\n\n## Shared Cache with Python\n\nRemember the second problem we mentioned? *\"No shared cache with the Python ecosystem.\"* That's now solved.\n\nswift-huggingface implements a Python-compatible cache structure that allows seamless sharing between Swift and Python clients:\n\n```\n~/.cache/huggingface/hub/\n├── models--deepseek-ai--DeepSeek-V3.2/\n│ ├── blobs/\n│ │ └── # actual file content\n│ ├── refs/\n│ │ └── main # contains commit hash\n│ └── snapshots/\n│ └── /\n│ └── config.json # symlink → ../../blobs/\n```\n\nThis means:\n\n- **Download once, use everywhere.** If you've already downloaded a model with the `hf` CLI or the Python library, swift-huggingface will find it automatically.\n- **Content-addressed storage.** Files are stored by their ETag in the `blobs/` directory. If two revisions share the same file, it's only stored once.\n- **Symlinks for efficiency.** Snapshot directories contain symlinks to blobs, minimizing disk usage while maintaining a clean file structure.\n\nThe cache location follows the same environment variable conventions as Python:\n\n1. `HF_HUB_CACHE` environment variable\n2. `HF_HOME` environment variable + `/hub`\n3. `~/.cache/huggingface/hub` (default)\n\nYou can also use the cache directly:\n\n```swift\nlet cache = HubCache.default\n\n// Check if a file is already cached\nif let cachedPath = cache.cachedFilePath(\n repo: \"deepseek-ai/DeepSeek-V3.2\",\n kind: .model,\n revision: \"main\",\n filename: \"config.json\"\n) {\n let data = try Data(contentsOf: cachedPath)\n // Use cached file without any network request\n}\n```\n\nTo prevent race conditions when multiple processes access the same cache, swift-huggingface uses file locking ([`flock(2)`](https://man7.org/linux/man-pages/man2/flock.2.html)).\n\n## Before and After\n\nHere's what downloading a model snapshot looked like with the old `HubApi`:\n\n```swift\n// Before: HubApi in swift-transformers\nlet hub = HubApi()\nlet repo = Hub.Repo(id: \"mlx-community/Llama-3.2-1B-Instruct-4bit\")\n\n// No progress tracking, no resume, errors swallowed\nlet modelDir = try await hub.snapshot(\n from: repo,\n matching: [\"*.safetensors\", \"*.json\"]\n) { progress in\n // Progress object exists but wasn't always accurate\n print(progress.fractionCompleted)\n}\n```\n\nAnd here's the same operation with swift-huggingface:\n\n```swift\n// After: swift-huggingface\nlet client = HubClient.default\n\nlet modelDir = try await client.downloadSnapshot(\n of: \"mlx-community/Llama-3.2-1B-Instruct-4bit\",\n to: cacheDirectory,\n matching: [\"*.safetensors\", \"*.json\"],\n progressHandler: { progress in\n // Accurate progress per file\n print(\"\\(progress.completedUnitCount)/\\(progress.totalUnitCount) files\")\n }\n)\n```\n\nThe API is similar, but the implementation is completely different — built on `URLSession` download tasks with proper delegate handling, resume data support, and metadata tracking.\n\n## Beyond Downloads\n\nBut wait, there's more! swift-huggingface contains a complete Hub client:\n\n```swift\n// List trending models\nlet models = try await client.listModels(\n filter: \"library:mlx\",\n sort: \"trending\",\n limit: 10\n)\n\n// Get model details\nlet model = try await client.getModel(\"mlx-community/Llama-3.2-1B-Instruct-4bit\")\nprint(\"Downloads: \\(model.downloads ?? 0)\")\nprint(\"Likes: \\(model.likes ?? 0)\")\n\n// Work with collections\nlet collections = try await client.listCollections(owner: \"huggingface\", sort: \"trending\")\n\n// Manage discussions\nlet discussions = try await client.listDiscussions(kind: .model, \"username/my-model\")\n```\n\nAnd that's not all! swift-huggingface has everything you need to interact with [Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers/index), giving your app instant access to hundreds of machine learning models, powered by world-class inference providers:\n\n```swift\nimport HuggingFace\n\n// Create a client (uses auto-detected credentials from environment)\nlet client = InferenceClient.default\n\n// Generate images from a text prompt\nlet response = try await client.textToImage(\n model: \"black-forest-labs/FLUX.1-schnell\",\n prompt: \"A serene Japanese garden with cherry blossoms\",\n provider: .hfInference,\n width: 1024,\n height: 1024,\n numImages: 1,\n guidanceScale: 7.5,\n numInferenceSteps: 50,\n seed: 42\n)\n\n// Save the generated image\ntry response.image.write(to: URL(fileURLWithPath: \"generated.png\"))\n```\n\nCheck the [README](https://github.com/huggingface/swift-huggingface) for a full list of everything that's supported.\n\n## What's Next\n\nWe're actively working on two fronts:\n\n**Integration with swift-transformers.** We have a [pull request in progress](https://github.com/huggingface/swift-transformers/pull/297) to replace `HubApi` with swift-huggingface. This will bring reliable downloads to everyone using swift-transformers, [mlx-swift-lm](https://github.com/ml-explore/mlx-swift-lm), and the broader ecosystem. If you maintain a Swift-based library or app and want help adopting swift-huggingface, reach out — we're happy to help.\n\n**Faster downloads with Xet.** We're adding support for the [Xet storage backend](https://huggingface.co/docs/hub/storage-backends), which enables chunk-based deduplication and significantly faster downloads for large models. More on this soon.\n\n## Try It Out\n\nAdd swift-huggingface to your project:\n\n```swift\ndependencies: [\n .package(url: \"https://github.com/huggingface/swift-huggingface.git\", from: \"0.4.0\")\n]\n```\n\nWe'd love your feedback. If you've been frustrated with model downloads in Swift, give this a try and [let us know how it goes](https://github.com/huggingface/swift-huggingface/issues). Your experience reports will help us prioritize what to improve next.\n\n## Resources\n\n- [swift-huggingface on GitHub](https://github.com/huggingface/swift-huggingface)\n- [swift-transformers](https://github.com/huggingface/swift-transformers)\n- [mlx-swift-examples](https://github.com/ml-explore/mlx-swift-examples)\n- [AnyLanguageModel](https://github.com/mattt/AnyLanguageModel)\n\n* * *\n\n*Thanks to the swift-transformers community for the feedback that shaped this project, and to everyone who filed issues and shared their experiences. This is for you.* ❤️\n", "dateCreated": "2026-10-04T12:50:30.804479567+00:00", "date_created": "2025-12-05T00:00:00+00:00", "date_modified": "2025-12-05T00:00:00+00:00", "date_published": "2025-12-05T00:00:00+00:00", "description": "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…", "external_url": "https://huggingface.co/blog/swift-huggingface", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/huggingface-co/2025/12/2025-12-05-introducing-swift-huggingface-the-complete-swift-client-for.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/huggingface-co/2025/12/2025-12-05-introducing-swift-huggingface-the-complete-swift-client-for.md" }, "id": "urn:aggr:item:afd47bca42f9cc065eb34c7292a31339f6fa3345", "isBasedOn": { "@id": "https://huggingface.co/blog/swift-huggingface" }, "mainEntity": { "@id": "https://huggingface.co/blog/swift-huggingface", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/huggingface-co/2025-12-05-introducing-swift-huggingface-the-complete-swift-client-for/#webpage" }, "dateModified": "2025-12-05T00:00:00+00:00", "datePublished": "2025-12-05T00:00:00+00:00", "headline": "Introducing swift-huggingface: The Complete Swift Client for Hugging Face", "timeRequired": "PT6M", "url": "https://huggingface.co/blog/swift-huggingface", "wordCount": 1347 }, "name": "Archived snapshot: Introducing swift-huggingface: The Complete Swift Client for Hugging Face", "preview": null, "reading_minutes": 6, "replicated_at": null, "source": "huggingface-co", "source_name": "Hugging Face - Blog", "summary": null, "tags": [], "temporalCoverage": "2026-10-04T12:50:30.804479567+00:00", "title": "Introducing swift-huggingface: The Complete Swift Client for Hugging Face", "url": "https://aggr.aymericbeaumet.com/items/huggingface-co/2025-12-05-introducing-swift-huggingface-the-complete-swift-client-for/", "word_count": 1347 }