In Swift Package Manager, how does `swift package resolve` differ from `swift package update`, and how do you stop CI picking up surprise versions?
answer
- one honours the file, one rewrites it
- latest eligible versions
- a dry run lists the changes
- fail when the file is out of date
- xcodebuild has the same switch
basics
~20 sswift 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.
solid answer
~40 s`swift package resolve` makes the checkouts match the manifests and `Package.resolved`, reusing every recorded version that is still eligible; it rewrites pins only when the manifests' requirements have changed. Build, run and test resolve the same way implicitly. `swift package update` is the deliberate move: it picks the latest versions the requirements allow, for all packages or only the ones you name, and rewrites the file; `--dry-run` lists what would change first. For CI, pass `--force-resolved-versions` (aliases `--disable-automatic-resolution` and `--only-use-versions-from-resolved-file`): SwiftPM then uses only the recorded versions and fails with an out-of-date resolved-file error if a manifest changed without its pins. `xcodebuild` has the matching `-onlyUsePackageVersionsFromResolvedFile`, also spelled `-disableAutomaticPackageResolution`.
code
bash · 13 lines# Local work: align with the committed pins (build does this implicitly)
swift package resolve
# Planned update: preview, then update one package or all of them
swift package update --dry-run
swift package update crash-reporter
# CI: use only Package.resolved, fail if it is out of date
swift package resolve --force-resolved-versions
swift build --force-resolved-versions
# Xcode project in CI
xcodebuild -resolvePackageDependencies -onlyUsePackageVersionsFromResolvedFile -scheme Shopgo deeper
Remember that update takes newer versions and rewrites Package.resolved, while resolve and normal builds stick to the recorded pins.
Explain when resolve does change pins, how update can be scoped to named packages or previewed with --dry-run, and what the locking option does.
Show how you make CI fail on a stale Package.resolved, with the SwiftPM option and the xcodebuild flag, and how you roll back one release cleanly.
Decide who runs updates and when, and make CI enforce the committed pins so that every version change arrives through a reviewed diff.
## Two commands, two intentions Swift Package Manager separates *making the checkouts consistent* from *moving to newer code*: - `swift package resolve` resolves the graph against the manifests and the committed `Package.resolved`, changing as little as possible. - `swift package update` asks for the **latest eligible** version of each dependency, then rewrites `Package.resolved`. Most commands, `swift build`, `swift run` and `swift test` among them, run resolution implicitly before they start and stop with an error if the graph cannot be resolved. So in daily work you rarely type `resolve`; you type `update` when you mean to take new releases. ## What resolve does The SwiftPM documentation describes three cases: - With a `Package.resolved` present, resolve uses the recorded versions "as long as they are still eligible". In most cases it performs no changes unless the manifest or the file changed. - When a teammate's commit changes `Package.resolved`, the next resolve updates the local checkouts to match it. - When a manifest requirement changes so a recorded version no longer fits, for example a new `exact:` pin, resolution runs again and rewrites the affected pins. Resolve also takes a package name to move one pin on purpose: `swift package resolve <name> --version 2.4.0`, or `--branch` and `--revision` for the unversioned forms. ## What update does `swift package update` with no arguments updates every dependency to the newest version its requirements allow, transitive packages included; `swift package update <name> ...` limits the update to the packages you name. Branch pins move to the branch's newest commit. `--dry-run` (short `-n`) prints the changes without applying them: ```plaintext [Dry-run] 1 dependency would change: ~ crash-reporter 3.0.0 -> crash-reporter 3.0.1 ``` An update never crosses a requirement's bounds: a `from: "3.0.0"` dependency can move to 3.9.0 but not to 4.0.0. A related option, `--skip-update`, skips refreshing dependencies from their remotes during a resolution, which can save time when the checkouts are already cached. | Command | Reads Package.resolved | May change pins | Typical use | |---|---|---|---| | `swift package resolve` | yes | only when a manifest requirement changed | after cloning or pulling | | `swift package update [names]` | as the starting point | yes, to the newest eligible | a planned dependency update | | `swift package resolve --force-resolved-versions` | yes | never; fails instead | CI and release builds | ## Locking CI to the committed file The point of committing `Package.resolved` is lost if CI quietly re-resolves. SwiftPM's option for that is `--force-resolved-versions`, with the aliases `--disable-automatic-resolution` and `--only-use-versions-from-resolved-file`; its help text reads "Only use versions from the Package.resolved file and fail resolution if it is out-of-date." It is accepted by `swift build` and `swift test` as well as `swift package resolve`. When someone edits a requirement without committing new pins, SwiftPM 6.4 stops with: ```plaintext error: an out-of-date resolved file was detected at .../Package.resolved, which is not allowed when automatic dependency resolution is disabled; please make sure to update the file to reflect the changes in dependencies. Running resolver because requirements have changed. ``` For Xcode projects built with `xcodebuild`, the Xcode 27 command-line tool documents the matching switches: - `-onlyUsePackageVersionsFromResolvedFile` and `-disableAutomaticPackageResolution`, both described as preventing packages "from automatically being resolved to versions other than those recorded in the `Package.resolved` file". - `-resolvePackageDependencies` to resolve as a separate, cacheable step. - `-skipPackageUpdates` to skip fetching from the remotes, and `-clonedSourcePackagesDirPath` to keep checkouts in a cache directory. ## A workable routine 1. Developers pull, and implicit resolution aligns them with the committed pins. 2. CI builds with `--force-resolved-versions` or `-onlyUsePackageVersionsFromResolvedFile`, so a stale file is a red build, not a silent upgrade. 3. Updates happen on a branch: run `swift package update --dry-run`, then `swift package update` for all or named packages, review the `Package.resolved` diff, and run the full test suite. 4. To back out one bad release, run `swift package resolve <name> --version <previous>` rather than editing JSON. ## Common confusions - Running `update` to "fix" a build after pulling, which silently upgrades unrelated packages. - Assuming `resolve` ignores `Package.resolved`; it is the command that honours it. - Assuming CI is locked just because the file is committed, without the option that makes a mismatch fatal. - Expecting `update` to adopt a new major version; it never crosses a requirement's upper bound, so a major upgrade starts with a manifest edit.
- A teammate bumped a requirement in Package.swift but forgot to commit Package.resolved. What does CI do with and without the locking option?Without it, CI re-resolves, rewrites its own copy of the file and builds whatever versions it picked, so the build is green but not what anyone reviewed. With `--force-resolved-versions` or `-onlyUsePackageVersionsFromResolvedFile`, SwiftPM detects the out-of-date resolved file and fails, telling the author to commit updated pins.
- How do you roll back a single dependency that an update moved to a broken release?Run `swift package resolve <name> --version <previous>`, which re-pins that package and rewrites its entry in `Package.resolved`, then commit the file. If the broken release must stay out for longer, tighten the requirement in the manifest too, for example with an upper bound below it, so the next `swift package update` does not bring it back.
- swift package resolve always fetches the newest versions, just like update.
- Committing Package.resolved alone guarantees CI never builds different versions.
- swift package update can move a from: "3.0.0" dependency to 4.0.0.
- The only way to undo one bad update is to hand-edit Package.resolved.
- --force-resolved-versions rewrites Package.resolved when the manifest changed.