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?
answer
- a comment SwiftPM parses first
- floor for the toolchain
- picks the PackageDescription API
- language mode default moves at 6.0
basics
~20 sThe 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.
solid answer
~40 sThe comment at the top of `Package.swift`, for example `// swift-tools-version: 6.1`, is read before the manifest is compiled. It is the minimum toolchain that may build the package, and it selects the PackageDescription version, so an API marked `@available(_PackageDescription, introduced: 6.2)` such as `.defaultIsolation(MainActor.self)` fails under 6.1 with `'defaultIsolation' is unavailable`, whatever toolchain is installed. It also moves defaults: from tools version 6.0, targets compile in the Swift 6 language mode unless the manifest overrides it. A toolchain older than the declared version stops with `is using Swift tools version 6.5.0 but the installed version is 6.4.0`, and during resolution SwiftPM skips dependency versions whose tools version is newer than the toolchain. Change it deliberately with `swift package tools-version --set`.
code
plaintext · 6 lines$ swift build # Package.swift declares: // swift-tools-version: 6.5
error: 'clientkit': package 'clientkit' is using Swift tools version 6.5.0 but the installed version is 6.4.0
$ swift build # Package.swift declares 6.1 and uses .defaultIsolation(MainActor.self)
Package.swift:9:30: error: 'defaultIsolation' is unavailable
PackageDescription.SwiftSetting.defaultIsolation:3:22: note: 'defaultIsolation' was introduced in PackageDescription 6.2go deeper
Recall that the comment at the top of Package.swift is parsed, sets the oldest toolchain that can build the package, and decides which manifest APIs compile.
Explain the @available(_PackageDescription, introduced:) gate with one example, and the 6.0 shift to Swift 6 mode as the default for targets.
Show how you raise the tools version safely: separate commit, per-target language-mode overrides, and awareness that clients on older toolchains resolve older releases.
Frame the tools version as a contract with consumers: which Xcode releases the package supports, and when version-specific manifests are worth their upkeep.
## What the line is Every `Package.swift` starts with a comment such as `// swift-tools-version: 6.1`. It looks like a comment, but SwiftPM reads it **before** it compiles the manifest, and it decides how the rest of the file is understood. The value is a semantic version whose patch component defaults to `0`, so `6.1` means `6.1.0`. The documentation places it on the first line; since Swift 6.0, SwiftPM also accepts it after leading comment lines, which matters when a licence header has to come first. The line does three jobs at once: - **It sets a floor for the toolchain.** It declares the oldest Swift toolchain, and so the oldest SwiftPM, that may build the package. - **It selects the manifest API.** The manifest is compiled against the PackageDescription version the line names, so APIs added in later versions are unavailable. - **It moves some defaults.** The most visible one is the Swift language mode that targets compile in. ## The floor: older toolchains stop A toolchain older than the declared version refuses the package outright. Swift 6.4 reading a manifest that declares 6.5 prints `package 'clientkit' is using Swift tools version 6.5.0 but the installed version is 6.4.0`. A manifest with no line at all is treated as tools version 3.1, which current toolchains no longer support, and the error suggests the current tools version instead. The same rule applies to dependencies. During resolution, a version of a dependency whose tools version is newer than the toolchain in use is ineligible, and SwiftPM moves on to the next-best version; if no version qualifies, resolution fails. How version requirements are chosen and pinned is a separate lesson, but this is why a library that raises its tools version can stop reaching clients who build with an older Xcode. ## The API gate: what the manifest may say Each PackageDescription declaration carries an `@available(_PackageDescription, introduced: X)` line, and the tools version is compared against it: | Manifest API | Tools version that added it | |---|---| | `resources:` on targets, `.process` and `.copy` | 5.3 | | `.plugin` targets and plugin products | 5.5 | | `.macro` targets (`CompilerPluginSupport`), the `package` access level | 5.9 | | `swiftLanguageModes`, per-target `.swiftLanguageMode(_:)` | 6.0 | | `traits:` and `.when(traits:)` conditions | 6.1 | | `.defaultIsolation(_:)`, `.strictMemorySafety()`, `.treatAllWarnings(as:)` | 6.2 | | `.iOS(.v27)` | 6.4 | Use a newer API under an older line and the manifest fails to compile: with `// swift-tools-version: 6.1`, `.defaultIsolation(MainActor.self)` produces `'defaultIsolation' is unavailable`, with a note that it was introduced in PackageDescription 6.2. Having the 6.4 toolchain installed does not help, because the line, not the toolchain, picks the API. The gate also works in the other direction: obsoleted spellings stop compiling and deprecated ones warn. `swiftLanguageVersions` is deprecated from tools version 6.0 in favour of `swiftLanguageModes`, and tools version 6.4 deprecates `.iOS(.v13)` and `.iOS(.v14)` with the message that iOS 15.0 is the oldest supported version. ## Defaults that move with it Raising the line is not only about new API. From tools version 6.0, targets compile in the **Swift 6 language mode** unless the manifest says otherwise. A target with a global `public var sharedCount = 0` that built cleanly at 5.10 fails at 6.0 with `var 'sharedCount' is not concurrency-safe because it is nonisolated global shared mutable state`. The manifest itself is compiled in the Swift 6 mode at that tools version too. The tools version and the language mode remain separate settings. A target can be held in the Swift 5 mode with `.swiftLanguageMode(.v5)`, or the whole package with `swiftLanguageModes`, without lowering the tools version, which is how teams adopt new manifest API before every module is migrated. ## Changing it on purpose 1. Pick the lowest tools version that has every manifest API you use, and check it against the Xcode releases your clients build with. 2. Change it with `swift package tools-version --set 6.1`, or `--set-current` for the toolchain in use, and build straight away. 3. Bump it in its own commit, and fix the language-mode fallout in the same review rather than in a dependent app. 4. If the package must still serve older toolchains, keep `Package.swift` at the newest tools version and add a version-specific manifest such as `[email protected]` for the older one, which is the arrangement the SwiftPM documentation recommends.
- Does raising the tools version change the Swift language mode the package's targets compile in?Yes, from tools version 6.0 targets default to the Swift 6 language mode, so a module with unprotected global state can stop compiling after the bump. The two settings stay separate: `.swiftLanguageMode(.v5)` on one target, or `swiftLanguageModes` for the package, keeps code in Swift 5 mode while the manifest uses 6.x API.
- What does SwiftPM do when a dependency's newest release declares a tools version newer than the toolchain?That release is ineligible, and resolution moves on to the next-best version that still meets the requirement. Only when no eligible version remains does SwiftPM report a resolution error. Clients on older toolchains therefore stay on older releases of the library rather than failing at once.
- Can a licence header come before the tools-version comment?Since Swift 6.0, yes: SwiftPM accepts the `// swift-tools-version:` comment on a line after leading comment lines. Older toolchains expect it on the first line, so a package that still supports them keeps it there.
- The swift-tools-version line is only a comment, so SwiftPM ignores it.
- A newer manifest API works under an older tools version as long as the installed toolchain is new.
- The tools version and the Swift language mode are the same setting.
- Without the line, SwiftPM assumes the version of the toolchain that is running.
- Raising the tools version is free because a newer toolchain builds every target exactly as before.
Assumes SwiftPM 6.4 (Swift 6.4, Xcode 27.0); the tools version named for each manifest API is read from PackageDescription's @available lines.