skip to content

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%

answer

  1. a range, not one release
  2. stops below the next major
  3. upToNextMinor keeps patch releases only
  4. exact pins collide across the graph
  5. branch and revision are unversioned

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.

solid answer

~40 s

`.package(url:from:)` is shorthand for `.upToNextMajor(from:)`: SwiftPM may choose any semantic-version tag from that version up to, not including, the next major, so `from: "1.2.3"` allows 1.2.4 or 1.3.0 but never 2.0.0. `.upToNextMinor(from: "1.4.2")` narrows that to 1.4.2 ..< 1.5.0, and a literal range such as `"1.0.0"..<"1.8.0"` sets both bounds. `exact:` allows one release, and the documentation warns it causes conflicts when another package needs a different one. `branch:` and `revision:` are unversioned: a branch pin moves to the newest commit whenever you update, a revision never moves, and a package that uses either cannot be depended on through a version requirement. I default to `from:` and keep the others for a known-bad release or packages developed in tandem.

code

swift · 27 lines
swift
// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "ShopKit",
    dependencies: [
        // 2.3.0 up to, not including, 3.0.0
        .package(url: "https://example.com/team/networking.git", from: "2.3.0"),
        // 1.4.2 up to, not including, 1.5.0
        .package(url: "https://example.com/team/logging.git", .upToNextMinor(from: "1.4.2")),
        // an explicit half-open range
        .package(url: "https://example.com/team/imaging.git", "1.0.0"..<"1.8.0"),
        // exactly 4.1.0 and nothing else
        .package(url: "https://example.com/team/analytics.git", exact: "4.1.0"),
        // whatever the branch points to when resolved or updated
        .package(url: "https://example.com/team/feature-flags.git", branch: "main"),
        // one commit, never moves
        .package(url: "https://example.com/team/crypto.git",
                 revision: "e74b07278b926c9ec6f9643455ea00d1ce04a021"),
    ],
    targets: [
        .target(name: "ShopKit", dependencies: [
            .product(name: "Networking", package: "networking"),
            .product(name: "Logging", package: "logging"),
        ]),
    ]
)

go deeper

for a junior

Recall that from: is a range up to the next major version, and name exact:, branch: and revision: as the narrower or unversioned alternatives.

for a middle

Explain the ranges upToNextMajor and upToNextMinor actually build, why 0.x packages deserve upToNextMinor, and which tools version introduced the labeled exact: form.

for a senior

Show why exact pins and branch pins hurt shared graphs: exact pins collide, and a release with a branch dependency cannot satisfy a version requirement.

for a principal

Frame requirement style as a team rule: ranges in libraries, temporary pins in the app with an owner and an expiry, and Package.resolved for reproducibility.

## What a version requirement says When a Package.swift manifest declares a remote dependency it gives Swift Package Manager two things: a **location** (a Git URL, or a registry identity) and a **requirement** that limits which releases it may choose. SwiftPM reads the dependency's Git tags, interprets them as **semantic versions** (major.minor.patch), and during **dependency resolution** picks one version of each package that satisfies every requirement in the graph. The documentation asks authors to tag releases with all three components. A requirement is therefore a *set of acceptable answers*, not an order to download one release. The release actually chosen is recorded separately, in `Package.resolved`. The same version forms apply to registry dependencies declared with `.package(id: "scope.name", from: "1.0.0")` (tools version 5.7 or later), where the registry's list of releases takes the place of Git tags; registry requirements have no branch or revision form. ## The version-based forms | Manifest spelling | Versions allowed | Typical use | |---|---|---| | `.package(url: u, from: "1.2.3")` | 1.2.3 ..< 2.0.0 | the default the documentation recommends | | `.package(url: u, .upToNextMajor(from: "1.2.3"))` | 1.2.3 ..< 2.0.0 | the same range, spelled out | | `.package(url: u, .upToNextMinor(from: "1.4.2"))` | 1.4.2 ..< 1.5.0 | patch releases only | | `.package(url: u, "1.0.0"..<"1.8.0")` | 1.0.0 ..< 1.8.0 | an explicit half-open range | | `.package(url: u, "1.0.0"..."1.7.9")` | 1.0.0 through 1.7.9 | a closed range | | `.package(url: u, exact: "4.1.0")` | 4.1.0 only | one known-good release | In the PackageDescription source, `from:` simply calls `.upToNextMajor(from:)`, which builds `version ..< Version(major + 1, 0, 0)`, while `.upToNextMinor(from:)` builds `version ..< Version(major, minor + 1, 0)`. Two consequences follow: - `from: "1.2.3"` accepts 1.2.4 and 1.3.0 but never 2.0.0, so adopting a new major release always takes a manifest edit. - `from: "0.4.0"` accepts everything below 1.0.0, including 0.5.0 and 0.9.0. For a pre-1.0 package whose minor releases may change its API, `.upToNextMinor(from:)` is the tighter fit. ## Exact versions `exact:` allows a single release. The PackageDescription documentation says exact requirements are not recommended because they "can cause conflicts in your dependency graph" when other packages depend on the same package: if one package needs 2.0.1 exactly and another needs 2.0.2 exactly, no version satisfies both. In an app, `exact:` is a reasonable way to step around one broken release, removed once a fixed release ships. It is not how builds become reproducible: a committed `Package.resolved` already records the chosen version under any range. ## Branch and revision requirements These two requirements are **unversioned**: - `branch: "main"` follows a branch. Resolution records the commit the branch pointed at, and `swift package update` moves the pin to the branch's newest commit. - `revision: "e74b072..."` names one commit. The documentation calls this an exceptional choice: the pin never moves, so you receive no updates at all. The documentation states the same restriction for both: a package that uses branch- or commit-based requirements cannot be added as a dependency to packages that use version-based requirements. With SwiftPM 6.4, resolution passes over such a release when an older release still satisfies the range, and otherwise fails with a message that the package "is required using a stable-version but ... depends on an unstable-version package". Branch and revision pins therefore belong in an app or in packages developed in tandem, and must be gone before a library is tagged. ## Choosing a requirement 1. Start with `from:` at the lowest version whose API you actually use. 2. Narrow to `.upToNextMinor(from:)` for pre-1.0 packages, or for a dependency whose minor releases have broken you before. 3. Use a range whose upper bound sits below a known-bad release, or `exact:`, as a temporary workaround in an app, never in a library. 4. Use `branch:` while co-developing two packages, and switch to a tagged release before shipping. 5. Use `revision:` only to pick up an untagged fix, with a note saying when it goes away. ## Tools-version notes The labeled `exact:` form needs `// swift-tools-version: 5.6` or later, and the `branch:` and `revision:` labels arrived in 5.5. From 5.6 the older unlabeled spellings such as `.package(url: u, .exact("1.0.0"))` or `.branch("main")` are deprecated, and the Swift 6.4 toolchain warns "use specific requirement APIs instead". Tools version 6.1 added an optional `traits:` parameter to these forms; it selects which of the dependency's package traits are enabled rather than which versions qualify.

  • Which versions does `from: "0.4.0"` allow, and why does that matter?
    It allows 0.4.0 up to, not including, 1.0.0, because `.upToNextMajor(from:)` only bumps the major number. A 0.x package may change its API in a minor release, so `from: "0.4.0"` can pull in 0.5.0 or 0.9.0 with breaking changes. `.upToNextMinor(from: "0.4.0")`, which stops below 0.5.0, is the safer requirement for a pre-1.0 dependency.
  • What happened to the `.package(url: u, .exact("1.0.0"))` spelling?
    Passing a requirement value such as `.exact(...)`, `.branch(...)` or `.revision(...)` as an unlabeled argument is deprecated from tools version 5.6, and the Swift 6.4 toolchain warns 'use specific requirement APIs instead'. The labeled `exact:`, `branch:` and `revision:` parameters replace it. The range helpers `.upToNextMajor(from:)` and `.upToNextMinor(from:)` used with `.package(url:_:)` remain current.
  • If `exact:` is discouraged, how does an app get reproducible builds?
    By committing `Package.resolved`. Resolution records the exact version and commit chosen for every package, direct and transitive, and later builds reuse those while they still satisfy the manifests. The requirement can stay a `from:` range, so `swift package update` can still move forward on purpose, while day-to-day builds stay identical across machines.

  • from: "1.2.3" means SwiftPM always uses exactly version 1.2.3.
  • from: "1.2.3" will move to 2.0.0 automatically once it is tagged.
  • exact: is the safest default because it is what makes builds reproducible.
  • upToNextMinor(from: "1.4.2") still accepts the 1.5.0 release.
  • A library can ship a branch: dependency and clients requiring it by version will cope.
  • A revision: pin is the recommended way to stay stable while still receiving fixes.

Assumes swift-tools-version 5.6 or later, checked against SwiftPM 6.4: the exact: label arrived in 5.6 (branch: and revision: in 5.5), and 5.6 deprecated the unlabeled .exact(), .branch() and .revision() forms.