Xcode Can't Find swift-transformers Package

šŸ¤—Transformers
1

Iā€™m trying to implement speech-to-text transcription in my Swift app using Hugging Faceā€™s swift-transformers package to run Whisper models locally.
Iā€™ve added the package to my Xcode project, but when I try to import it, I get the error:
No module found ā€˜Transformersā€™
What Iā€™ve tried:

Added the package via File ā†’ Add Package Dependencies using the GitHub URL
The package appears in my Package Dependencies in the project navigator
Cleaned and rebuilt the project

image
image1822Ɨ356 79.8 KB

Its showing in the Frameworks as well, however, still module not found?

1 Like
2

I donā€™t have a Mac, so I canā€™t test it on my end, but something like thisā€¦?

Root cause: the package is fetched, but the product you need is not linked to the target that compiles your file, or youā€™re importing the wrong module. In swift-transformers, importable modules are Hub, Tokenizers, Models, and Generation. Transformers is a library name used in Package.swift examples, not a module you can import in code. Link the correct package product(s) to your target and import those modules. (Hugging Face)

Fix fast

  1. Xcode target linkage
    Select your app target ā†’ General ā†’ Frameworks, Libraries, and Embedded Content ā†’ + ā†’ Add Package Productā€¦ ā†’ pick the product(s) you will import, e.g. Hub, Tokenizers, Models, Generation. Build. This is the step most people miss. (Kilo Loco)

  2. Or use Package.swift
    Declare the package and add the product(s) to the target dependencies. The README shows this pattern. (GitHub)

// deps: https://github.com/huggingface/swift-transformers
// pin: use latest stable listed on SPI
//      https://swiftpackageindex.com/huggingface/swift-transformers
dependencies: [
  .package(url: "https://github.com/huggingface/swift-transformers", from: "1.1.1")
],
targets: [
  .target(
    name: "App",
    dependencies: [
      .product(name: "Hub",         package: "swift-transformers"),      // https://huggingface.co/blog/swift-transformers
      .product(name: "Tokenizers",  package: "swift-transformers"),
      // .product(name: "Models",    package: "swift-transformers"),
      // .product(name: "Generation",package: "swift-transformers")
      // If you used `.product(name: "Transformers", ...)` in the target,
      // keep imports aligned with the actual modules you use.
    ])
]

Tokenizers and Hub are the most used modules. Models and Generation contain Core ML helpers. (Hugging Face)

  1. Import the module you actually linked
// swift-transformers
// docs: https://huggingface.co/blog/swift-transformers
import Hub
import Tokenizers
// import Models
// import Generation

If you write import Transformers while only linking Hub or Tokenizers, Xcode reports ā€œNo such module ā€˜Transformersā€™.ā€ This misunderstanding shows up in field reports as well. (Stack Overflow)

  1. Reset SPM state if builds still fail
    Xcode ā†’ File ā†’ Packages ā†’ Reset Package Caches, then Resolve Package Versions. This clears stale package metadata that often causes phantom ā€œNo such moduleā€ errors. (TelemetryDeck)

  2. Multi-target hygiene
    Every target that imports these modules must link the same products. Verify Link Binary With Libraries for each target. (Swift Forums)

  3. Edge case: custom build directories
    If you use custom configurations like StagingDebug, mismatched CONFIGURATION_BUILD_DIR values can break SPM linkage and produce ā€œNo such module.ā€ Align names or paths. (Swift Forums)

Background, with context

  • Packages vs products vs modules. Adding a package fetches code. You must link a package product to your target to expose a module you can import. Xcode hides this behind ā€œAdd Package Productā€¦ā€ in the targetā€™s Frameworks, Libraries, and Embedded Content. (Kilo Loco)
  • swift-transformers module layout. The project ships separate modules: Hub for HF Hub downloads and caching, Tokenizers for fast tokenization and chat templating, plus Models and Generation for Core ML helpers. The 1.0 release formalized Tokenizers and Hub as first-class top-level modules. (Hugging Face)
  • Versioning. Latest stable is 1.1.x with active maintenance. If you pinned old tags, update. Check Swift Package Index for version and toolchain support. (The Swift Package Index)

Whisper transcription on device

For Whisper STT on Apple platforms, the maintained path is WhisperKit, which uses swift-transformers pieces under the hood and adds ASR-specific runtime features (streaming, VAD, timestamps). Use WhisperKit unless youā€™re building a custom pipeline. (Hugging Face)

// WhisperKit: https://github.com/argmaxinc/WhisperKit
import WhisperKit

let wk = try await WhisperKit()
let result = try await wk.transcribe(audioPath: audioURL.path)
// result?.text -> transcript

Working examples you can compile

Download model files and tokenize text

// Hub + Tokenizers examples from README
//   https://github.com/huggingface/swift-transformers#examples
import Hub
import Tokenizers

let repo = Hub.Repo(id: "mlx-community/Qwen2.5-0.5B-Instruct-2bit-mlx") // https://huggingface.co/mlx-community
let modelDir = try await Hub.snapshot(from: repo, matching: ["config.json", "*.safetensors"])
let tok = try await AutoTokenizer.from(pretrained: "mlx-community/Qwen2.5-0.5B-Instruct-4bit")
let ids = try tok.encode("hello world")
print(modelDir, ids)

This compiles only if your target links Hub and Tokenizers. (GitHub)

Diagnostic checklist

  • Package product linked to the importing target: Yes/No. If no, add via Add Package Productā€¦. (Kilo Loco)
  • Import lines match linked modules: Hub / Tokenizers / Models / Generation. (Hugging Face)
  • Reset caches and resolve packages. (TelemetryDeck)
  • For extensions or multiple targets, verify each targetā€™s Link Binary With Libraries. (Swift Forums)
  • Custom configs: confirm CONFIGURATION_BUILD_DIR alignment. (Swift Forums)
  • Version sanity: update to latest 1.1.x. Confirm toolchain support on SPI. (The Swift Package Index)

Similar reports and fixes

  • ā€œTransformers is not a module.ā€ Answer notes the importable modules are Hub, Tokenizers, Generation, Models. (Stack Overflow)
  • Confusion about adding a package vs adding a package product. Step-by-step article shows the exact Add Package Productā€¦ flow in Xcode. (Kilo Loco)
  • General SPM ā€˜No such moduleā€™ threads. Typical culprits: target linkage and build path overrides. One case resolved by fixing CONFIGURATION_BUILD_DIR. (Swift Forums)

Curated references

Primary docs and repos

  • swift-transformers README and examples. Module overview and Package.swift usage. (GitHub)
  • 1.0 release post. Explains top-level modules and usage patterns. Notes WhisperKit relies on Hub and Tokenizers. (Hugging Face)
  • Swift Package Index page. Versions, toolchain, platforms. (The Swift Package Index)

How-to: add the right product

  • Add or re-add a package product to a target in Xcode. Clear, screenshot-driven guide. (Kilo Loco)

Whisper on device

  • WhisperKit repo and SPI entry. Feature set and SPM setup. (GitHub)

Troubleshooting SPM

Bottom line

  • Link the product to the target.
  • Import the module you linked: Hub, Tokenizers, Models, Generation.
  • Reset caches if needed.
  • For Whisper STT, prefer WhisperKit unless you need a custom pipeline. (Hugging Face)