skip to content

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%

answer

  1. the result, not the request
  2. every package in the graph
  3. version or branch plus a commit
  4. only the top-level package's file counts

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.

solid answer

~50 s

`Package.resolved` is the record of what resolution chose, not of what the manifest asked for. For each package in the graph, including transitive ones, it stores a pin with the `identity`, `kind` and `location`, and a `state` holding the commit `revision` and, where one applies, the `version` or `branch`. When the file exists, `swift build`, `swift test` and `swift package resolve` reuse those versions as long as they still satisfy the manifests, so every machine builds the same code. That only applies to the top-level package: when your package is resolved as someone else's dependency, its `Package.resolved` is ignored and their resolution picks the latest eligible versions within your manifest's requirements. So an app commits the file; a library may keep one for its own CI, but it cannot pin anything for clients. For an Apple-platform app the file lives inside the `.xcodeproj` or `.xcworkspace`.

code

bash · 6 lines
bash
# After cloning an app: resolve to the pinned versions and list the graph
swift package resolve
swift package show-dependencies

# Change one pin on purpose, then commit the rewritten Package.resolved
swift package resolve networking --version 2.4.0

go deeper

for a junior

Recall that Package.resolved stores the chosen version and commit of every dependency, and that an app commits it so everyone builds the same code.

for a middle

Explain the pin fields, why transitive packages are pinned, and why the file is ignored when the package is someone else's dependency.

for a senior

Show how the root-only rule shapes a library: its CI can be green on pinned versions while clients resolve newer ones, so test without the file too.

for a principal

Treat the file as the team's contract for what ships: committed for apps, changed only through reviewed updates, and never relied on to protect a library's clients.

## What resolution produces A Package.swift manifest states **requirements**: ranges, exact versions, branches, commits. **Dependency resolution** walks the whole graph, the root package's dependencies and their dependencies recursively, and chooses one concrete version of each package that satisfies every requirement at once. Swift Package Manager writes the outcome to a file named `Package.resolved` at the top level of the package. For an app on an Apple platform, the PackageDescription documentation says the file lives inside the `.xcodeproj` or `.xcworkspace` instead. The manifest says *what is acceptable*; `Package.resolved` says *what was picked*. Keeping both is what lets a team allow updates in principle while building identical code in practice. ## What the file contains A file written by SwiftPM 6.4 is JSON with a format `version` (currently 3), an `originHash`, and a list of **pins**, one per package: ```plaintext { "identity" : "networking", "kind" : "remoteSourceControl", "location" : "https://example.com/team/networking.git", "state" : { "revision" : "4b99975677236d13f0754339864e5360142ff5a1", "version" : "2.4.1" } } ``` | Field | Meaning | |---|---| | `identity` | the package identity: the last path component of the URL, lower-cased, without `.git` | | `kind` | where the package came from, such as `remoteSourceControl` for a Git URL | | `location` | the URL or path it was fetched from | | `state.version` | the semantic version chosen under a version requirement | | `state.branch` | the branch followed under a branch requirement | | `state.revision` | the commit, recorded for every source-control pin | Points worth noticing: - **Transitive packages are pinned too.** A package that appears only because one of your dependencies needs it still gets its own pin. - **The commit sits beside the tag or branch**, so even a branch requirement builds the same code until someone updates it. - **A local `.package(path:)` dependency gets no pin**; it uses whatever is on disk. ## How SwiftPM uses the file 1. When the file exists and you build, run, test or call `swift package resolve` on the top-level package, SwiftPM resolves to the recorded versions as long as they are still eligible under the manifests. 2. When the file changes, for example because a teammate committed an update, the next resolve brings the local checkouts in line with it. 3. When a manifest requirement changes so that a recorded version no longer fits, resolution runs again and rewrites the affected pins. 4. `swift package update` deliberately moves dependencies to the latest eligible versions and rewrites the file. 5. Without the file, every machine resolves on its own and a fresh clone starts from the latest eligible version of each dependency, so two developers can build different code from the same commit. CI can go further: `swift build --force-resolved-versions` uses only the recorded versions and fails when the file is out of date, instead of quietly resolving again and building something nobody reviewed. ## The top-level package only The documentation is explicit that `Package.resolved` "does not pin dependency versions for packages used as libraries". When your package is resolved as a dependency of another, its own file is ignored, and the consumer's resolution chooses the latest eligible versions that your manifest's requirements allow. | Package role | Commit `Package.resolved`? | Effect | |---|---|---| | App, command-line tool or server | yes | every developer and CI build uses the same graph | | Library consumed by others | optional | pins only the library's own CI and local builds; clients never see it | For a library, the manifest's requirements are the only lever it has over its clients. That is why a library keeps its ranges wide, avoids `exact:` pins, and never ships with branch or commit requirements. ## Common mistakes - Listing `Package.resolved` in `.gitignore` for an app, so CI and teammates drift onto different versions. - Hand-editing a pin instead of running `swift package update <name>` or `swift package resolve <name> --version <v>`. - Settling a merge conflict in the file by keeping lines from both sides, instead of keeping one side and running resolution again. - Expecting a library's committed file to shield its clients from a bad upstream release; only a requirement in the library's manifest can do that. - Committing the file while a dependency is in `swift package edit` mode; in SwiftPM 6.4 edit mode removes that dependency's pin until `swift package unedit`.

  • Your library's CI is green with its committed Package.resolved, but a client reports a build failure. How can that happen?
    The client's resolution ignored your `Package.resolved` and chose the latest versions your manifest allows, which your CI never built. Run a CI job that resolves without the file, or with `swift package update` first, to test the newest eligible versions, and tighten a requirement in your manifest if one release is incompatible.
  • Where does Package.resolved live for an Xcode app project, and does it matter which copy you commit?
    The PackageDescription documentation says that for an Apple-platform app it lives inside the `.xcodeproj` or `.xcworkspace` rather than at a package root. Commit the copy inside the project or workspace that the team and CI open, so the pins everyone builds from are the ones under review.

  • Package.resolved lists only the dependencies written in my own manifest.
  • Committing Package.resolved in a library pins versions for every app that uses it.
  • Package.resolved should be gitignored because it is a generated build artefact.
  • A branch dependency cannot be reproduced because the file stores only the branch name.
  • Package.resolved replaces the manifest's requirements, so editing the file is how you upgrade.