skip to content

Swift Package Manager

Swift's built-in dependency and build manager: a Package.swift manifest of products, targets and dependencies, resolved into a lockfile. Apple-platform roles ask it against CocoaPods.

on this pageshow

explore

questions

22

When you add a Swift package to an iOS app in Xcode, what do you choose, and why can an import still fail?

level: juniorimportance: must knowfreq 70%

answer

  1. two separate steps
  2. a URL plus a version requirement
  3. products are linked per target
  4. import the module, not the package

basics

~20 s

You give Xcode the package's repository URL and a version requirement, then choose which library products to link into which targets. Declaring the package links nothing: importing a module that no linked product brings in fails with No such module.

solid answer

~50 s

Adding a package is two steps. First the project gains a **package dependency**: a repository URL plus a version requirement, typically "from `2.3.0` up to the next major version"; the resolved versions are recorded in `Package.resolved`. Second, you choose which of the package's **library products** to link into which target — the app, a widget extension, a test bundle. A product is what another project depends on; the targets inside it are Swift modules, and your code imports a module name and sees only its `public` API. So `import Payments` fails with `No such module` when nothing the target links brings in `Payments`, and a package whose `platforms` require a newer OS than the target fails the build. Plain SwiftPM has the same split: a dependency no target uses only earns a "not used by any target" warning.

code

bash · 2 lines
bash
swift package add-dependency https://github.com/apple/example-package-playingcard --from 3.0.0
swift package add-target-dependency PlayingCard DeckOfPlayingCards --package example-package-playingcard

go deeper

for a junior

Recall the two steps: declare the package with a URL and a version requirement, then link a library product to each target that imports it. Know that you import a module name.

for a middle

Explain products versus targets versus modules, why an unlinked product gives No such module, and how a package's platforms list can fail an app's build.

for a senior

Diagnose a failing import quickly: wrong target linked, product versus module name, deployment target below the package's platforms, or a resolution failure upstream of linking.

for a principal

Set the team rule for adding a dependency: what to read in its manifest first, who approves new products in the app, and why each link should be deliberate rather than blanket.

## Two things happen when you add a package When an iOS project takes a third-party Swift package, two separate decisions are recorded, and most "it won't import" problems come from confusing them. 1. **The package dependency.** The project learns *where* the package lives (a Git repository URL) and *which versions* are acceptable (a version requirement). Swift Package Manager (SwiftPM) resolves the whole dependency graph — the package and everything it depends on — and records the exact versions it chose in a file named `Package.resolved`. 2. **Linking products to targets.** A package declares **products**: libraries, executables and plugins. An app target can only link a **library product**. You choose, per target, which products to link: the app target, a widget or share extension, a test bundle. Each target that imports the code needs its own link. Declaring the dependency alone makes nothing importable. SwiftPM's own documentation shows the same rule from the command line: after adding a dependency to a package manifest, `swift build` succeeds with a warning that the dependency "is not used by any target", and `import PlayingCard` fails with `No such module 'PlayingCard'` until a target depends on the product. ## Products, targets and modules | Term | What it is | Who refers to it | |---|---|---| | **Package dependency** | A repository URL plus a version requirement | The project or a `Package.swift` manifest | | **Product** | A named library (or executable, or plugin) a package vends | The target that links it | | **Target** | A building block inside the package; each one is a module | Other targets in the same package | | **Module** | The unit of code and access control you `import` | Your Swift source files | The names can differ. A product called `Networking` may bundle two targets, `HTTPCore` and `HTTPCache`; your source writes `import HTTPCore`, the module name, not `import Networking`. Only the module's `public` (and `open`) declarations are visible to the app — the language rules for access levels are covered with Swift's access control. ## Why an import still fails - **The product is linked to a different target.** It was added to the app, but the widget extension that imports the same module was never given the product. - **The import names the product or repository, not the module.** The package `example-package-playingcard` vends a library whose module is `PlayingCard`. - **The package's `platforms` exceed the target's deployment target.** If the manifest declares `.iOS(.v17)` and the app target supports iOS 16, the build fails with an error that the package product requires a newer minimum platform version than the target supports. - **The API is not public.** The import succeeds, but using an `internal` type reports that it is inaccessible due to its protection level — a different error from `No such module`. - **Resolution failed.** If SwiftPM cannot find versions that satisfy every requirement in the graph, nothing from the package builds; that is a version-requirement problem, not a linking one. ## The same steps in a pure package Outside Xcode, the two steps are two manifest edits, and SwiftPM ships commands that make them: - `swift package add-dependency <url> --from <version>` adds the `.package(url:from:)` entry. - `swift package add-target-dependency <product> <target> --package <package>` adds the product to a target's `dependencies`. Seeing both edits side by side is the clearest way to explain the Xcode flow in an interview: the dependency says *what may be fetched*, the target dependency says *who links it*. ## Finding a package before you add it The **Swift Package Index** is a public index of Swift packages that also hosts package documentation; SwiftPM's own getting-started guide links the swift-testing documentation there. Before adding a package, read its `Package.swift`: the `platforms` it requires, the products it vends, whether it pulls in a closed-source binary target, and whether its release tags are full three-part semantic versions — SwiftPM interprets only tags with major, minor and patch components as versions. ## What a reviewer looks for - A product linked only into the targets that import it, not into every target "just in case". - A version requirement that allows bug-fix releases rather than a hard-coded commit. - `Package.resolved` committed for the app, so every machine builds the same versions. - Import lines that name modules, and no reliance on a module that merely happens to be reachable through another product.

  • The app target links a package's product, but the app's widget extension imports the same module and fails to build. Why?
    Linking is per target. The product was linked into the app target only, so the extension's compile has no such module. Link the product into the extension target as well; the package dependency itself is declared once for the project and does not need to be added again.
  • A package vends a product named `Networking` made of the targets `HTTPCore` and `HTTPCache`. What does app code import?
    The module it uses: `import HTTPCore` and, if needed, `import HTTPCache`. A library product is a bundle of targets, and each target is its own module. The product name is what you link; the module name is what you import.
  • What do you check in a package before adding it to a production app?
    Its `Package.swift`: the `platforms` it requires against your deployment target, the library products it vends, any binary targets it downloads, and its tools version. Then its release tags, which must be full major.minor.patch versions for SwiftPM to treat them as versions, its license and its documentation, which the Swift Package Index hosts for many packages.

  • Adding the package URL to the project makes its modules importable in every target.
  • You import the repository or product name, so the import must match the package's URL.
  • A No such module error means the API you use is marked internal.
  • A package whose platforms require iOS 17 still builds into an app that targets iOS 16.
  • Every product a package vends gets linked into the app automatically.
open as a page

In a Swift package, what does the `// swift-tools-version:` line in Package.swift control, and what goes wrong when it is set too low or too high?

level: juniorimportance: must knowfreq 58%

basics

~20 s

The swift-tools-version comment in Package.swift names the oldest Swift toolchain that can build the package and picks the PackageDescription API the manifest compiles against: too low hides newer manifest APIs, too high locks out older toolchains.

open as a page

What does Swift Package Manager record in Package.resolved, and why does an app commit it while a library's copy is ignored by its clients?

level: juniorimportance: must knowfreq 70%

basics

~20 s

Package.resolved records what resolution chose: for every package in the graph, transitive ones included, its identity, location, commit and, where one applies, version or branch. SwiftPM honours it only for the top-level package, so apps commit it and libraries cannot pin clients.

open as a page

In a Package.swift manifest, which versions does `.package(url:from:)` let SwiftPM choose, and when would you write `exact:`, `branch:` or `revision:` instead?

level: juniorimportance: must knowfreq 72%

basics

~20 s

from: "1.2.3" lets SwiftPM pick any tagged release from 1.2.3 up to, but not including, 2.0.0. exact: allows one release, branch: follows a branch and revision: freezes one commit; the last two leave versioning behind.

open as a page

In a Swift package manifest, how do targets map to modules, and what does a library product expose to the packages that depend on it?

level: middleimportance: must knowfreq 62%

basics

~20 s

Each SwiftPM target builds one module, by default from Sources/<TargetName>. A library product is the outward-facing unit: it vends the public API of the targets it lists, and other packages depend on products, never on bare targets.

open as a page

In Swift Package Manager, how does `swift package resolve` differ from `swift package update`, and how do you stop CI picking up surprise versions?

level: middleimportance: must knowfreq 58%

basics

~20 s

swift package resolve keeps the versions in Package.resolved while they still fit the manifests; swift package update moves to the newest eligible versions and rewrites the file. In CI, --force-resolved-versions makes a stale file fail instead of re-resolving.

open as a page

In a Package.swift manifest, how do you apply a build tool plugin that another package vends to one of your targets?

level: juniorimportance: should knowfreq 40%

basics

~20 s

Add the package that vends the plugin to the manifest's dependencies, then list the plugin in that target's plugins: array as .plugin(name:package:). SwiftPM then invokes the plugin whenever it builds that target; there is no separate run step.

open as a page

In a Swift package target that bundles resources, how does its code load them through Bundle.module, and why does Bundle.main miss them?

level: middleimportance: should knowfreq 48%

basics

~20 s

SwiftPM puts a target's resources in their own bundle and generates an internal Bundle.module accessor for that module. Package code loads files and assets through Bundle.module; Bundle.main is the app's bundle, which does not hold them.

open as a page

How does an iOS app consume a local Swift package kept in its own repository, and how does that differ from a remote package dependency?

level: middleimportance: should knowfreq 45%

basics

~20 s

A local package is a folder with its own Package.swift inside the app's repository; the app links its library products like any package. SwiftPM uses whatever code sits at the path: no version requirement, no tag, edits build immediately.

open as a page

In a Package.swift manifest, when do you declare a target's resources with `.process` versus `.copy`, and what goes wrong with each?

level: middleimportance: should knowfreq 40%

basics

~20 s

Declare .process for files SwiftPM may optimise, which land flattened at the resource bundle's top level, and .copy for a file or folder that must stay untouched with its directory structure, such as nested JSON fixtures.

open as a page

In Swift Package Manager, how does a build tool plugin differ from a command plugin in when it runs and what it may do?

level: middleimportance: should knowfreq 40%

basics

~20 s

A build tool plugin is applied to a target and called during builds; it only returns commands that the build runs. A command plugin runs when invoked as swift package <verb>, does the work itself, and may request write or network permissions.

open as a page

In a SwiftPM build tool plugin, where should generated Swift files be written, and how do they end up compiled into the target?

level: middleimportance: should knowfreq 30%

basics

~20 s

Into the plugin work directory, context.pluginWorkDirectoryURL, listed as the command's outputs. SwiftPM compiles generated .swift outputs into the target the plugin was applied to as if they sat in its source directory, and treats other outputs as resources.

open as a page

A vendor ships a closed-source analytics SDK as a zipped XCFramework; how do you declare it with SwiftPM's binaryTarget, and what does its checksum guard?

level: seniorimportance: should knowfreq 30%

basics

~10 s

Declare .binaryTarget(name:url:checksum:) with an https URL to the zip and the SHA-256 that swift package compute-checksum prints. SwiftPM rejects a downloaded archive whose checksum differs, so a swapped or corrupted file never builds.

open as a page

In a Package.swift manifest, how do you wire a Swift macro so app code can use it, and why must app targets import a library target rather than the `.macro` target?

level: seniorimportance: should knowfreq 28%

basics

~20 s

Import CompilerPluginSupport, declare a .macro target depending on swift-syntax's SwiftSyntaxMacros and SwiftCompilerPlugin, plus a regular target that depends on it and declares the macros. Clients import that library target; the macro target is a compiler plugin.

open as a page

In a Package.swift manifest, how do `swiftSettings` set one target's language mode, default isolation and conditional flags, and why is `unsafeFlags` a problem in a published library?

level: seniorimportance: should knowfreq 38%

basics

~20 s

swiftSettings apply per target: .swiftLanguageMode(.v5) (tools 6.0) keeps one target in Swift 5 mode, .defaultIsolation(MainActor.self) (6.2) makes unannotated code main-actor isolated, and .define adds conditions. unsafeFlags makes products containing the target ineligible for use by other packages.

open as a page

A SwiftPM build tool plugin generates Swift types from a GraphQL schema; when should it return .buildCommand rather than .prebuildCommand, and what does each cost?

level: seniorimportance: should knowfreq 25%

basics

~20 s

Return .buildCommand when output names follow from input paths alone: it joins the build graph and reruns only when needed. Use .prebuildCommand only when names depend on file contents; it runs before every build and needs a binary-target tool.

open as a page

A SwiftPM command plugin that reformats sources works on a laptop but fails in CI with a permission error; why, and how do you fix it?

level: seniorimportance: should knowfreq 30%

basics

~20 s

The plugin declares .writeToPackageDirectory(reason:), and SwiftPM grants that only after approval: at a terminal it asks yes or no, but without one it fails with an error. Grant it in CI by passing --allow-writing-to-package-directory to swift package.

open as a page

An app's two SwiftPM dependencies require incompatible major versions of a shared logging package; how does SwiftPM report the conflict, and how do you resolve it?

level: seniorimportance: should knowfreq 45%

basics

~20 s

Resolution fails with "Dependencies could not be resolved because..." and a chain naming which release needs which range of the shared package. Fix it with a dependency release that accepts the other major, an older compatible release, or a temporary root override.

open as a page

As the lead moving a 300k-line iOS app's features into local Swift packages, where do you draw the package and target seams, and what does it cost?

level: principalimportance: should knowfreq 38%

basics

~20 s

Start with one local package: shared leaf targets (design system, networking, vendor wrappers) and one target and library product per feature, depending only downward. The cost is public API, Bundle.module rewrites, manifest upkeep and many more modules to build.

open as a page

As iOS lead for an app with fifteen SwiftPM dependencies, what policy would you set for Package.resolved, update cadence, branch pins and where packages are fetched from?

level: principalimportance: should knowfreq 35%

basics

~20 s

Commit Package.resolved and make CI refuse a stale one; take updates as small reviewed pull requests on a schedule, with security fixes out of band; ban branch and revision pins from release builds; decide deliberately between Git URLs, mirrors and a private registry.

open as a page

How does `swift package edit` let you patch a remote SwiftPM dependency in place, and how does it compare with a root-level `.package(path:)` override?

level: middleimportance: nice to knowfreq 25%

basics

~20 s

swift package edit puts a dependency into an editable Git checkout under Packages/, built for every use of the package until swift package unedit. A root .package(path:) with the same identity does the same through the manifest.

open as a page

In a Package.swift manifest with tools version 6.1, how do package traits make a dependency optional, and how does a client choose which traits it gets?

level: seniorimportance: nice to knowfreq 18%

basics

~20 s

A package declares traits in Package(traits:), sets defaults with .default(enabledTraits:), links an optional product under condition: .when(traits:) and guards code with #if. A client lists traits on its .package dependency; any list replaces the defaults unless it includes .defaults.

open as a page