skip to content

In Swift, how do #available, #unavailable and @available let an app call an API newer than its deployment target?

level: middleimportance: must knowfreq 65%

answer

  1. compile-time error, run-time branch
  2. SDK versus deployment target
  3. the mandatory * wildcard
  4. guard refines the rest of the scope
  5. #unavailable has no wildcard

basics

~20 s

@available records the OS versions a declaration needs; calling it from code that may run on an older OS fails to compile unless the call sits inside an #available check, which tests the OS at run time. #unavailable is the inverse.

solid answer

~50 s

The compiler checks every use of an API against the **deployment target**. Calling a function marked `@available(iOS 26, *)` from code that may run on iOS 17 fails with "'uploadInBackground' is only available in iOS 26 or newer", plus fix-its to add an `if #available` check or an `@available` attribute. `if #available(iOS 26, macOS 26, *)` tests the running OS at **run time**, and inside its body the compiler treats those APIs as available; `guard #available(…) else { return }` refines the rest of the scope. The trailing `*` is required and means the deployment target on every other platform. `#available` is not a `Bool`, so `!#available` is rejected; `#unavailable(iOS 26)`, from Swift 5.6, is the inverted form with the `*` implicit. `@available` also carries `deprecated`, `obsoleted`, `unavailable`, `renamed` and `message`, and Swift 6.4 adds `anyAppleOS 26` for every Apple platform at once.

code

swift · 28 lines
swift
@available(iOS 26, macOS 26, *)
func uploadInBackground(_ name: String) -> String { "background: \(name)" }

func uploadInForeground(_ name: String) -> String { "foreground: \(name)" }

func startUpload(_ name: String) -> String {
    if #available(iOS 26, macOS 26, *) {
        return uploadInBackground(name)   // refined: iOS 26 / macOS 26 APIs allowed
    } else {
        return uploadInForeground(name)
    }
}

func retryUpload(_ name: String) -> String {
    guard #available(iOS 26, macOS 26, *) else {
        return uploadInForeground(name)
    }
    return uploadInBackground(name)       // refined for the rest of the function
}

func needsUpdateBanner() -> Bool {
    if #unavailable(iOS 26, macOS 26) {   // no '*': it is implicit here
        return true
    }
    return false
}

print(startUpload("a.png"), retryUpload("b.png"), needsUpdateBanner())

go deeper

for a junior

Recall that calling a newer API needs an if #available check, that the * is required, and that #unavailable is the inverted form.

for a middle

Explain the split between the compile-time @available constraint and the run-time #available test, and how guard #available refines the rest of a scope.

for a senior

Diagnose 'only available in iOS 26 or newer' errors, choose between wrapping a call and annotating the caller, and keep #if os and #available apart in review.

for a principal

Set how far below the newest OS the deployment target stays, given how many availability branches and fallback paths each extra year of support costs.

## SDK versus deployment target An Apple-platform app is compiled against an **SDK**, say iOS 26, but declares a **deployment target**: the oldest OS it promises to run on, say iOS 17. Every declaration in the SDK carries availability information. The compiler checks each use against the deployment target, so code that would call a missing symbol on an older OS is rejected when you build, not when a user on iOS 17 opens the screen. Building against the newest SDK makes new APIs *visible*; it does not make them *present* on old systems. ## `@available` on declarations `@available` states a declaration's life cycle per platform: - `@available(iOS 26, macOS 26, *)`: the short form, introduced in those versions; `*` covers every other platform at its deployment target. - `introduced:`, `deprecated:` and `obsoleted:` take versions in the long form, for example `@available(iOS, introduced: 15, deprecated: 26, message: "Use the async API")`. - `unavailable` makes the declaration unusable on that platform; `@available(*, unavailable)` makes it unusable everywhere. - `renamed:` and `message:` supply text the compiler shows with its diagnostic, and a rename gets a fix-it. Marking your own function `@available(iOS 26, *)` lets its body use iOS 26 APIs freely and moves the obligation to check onto its callers. A call from code that may run lower fails with "'uploadInBackground' is only available in iOS 26 or newer", and the compiler offers two notes: add an `if #available` version check, or add `@available` to the enclosing function. ## `#available` and `guard #available` 1. `if #available(iOS 26, macOS 26, *)` is a **run-time** test of the OS the code is running on. 2. Inside the `if` body the compiler treats the listed versions as available: the check *refines* availability for that scope. 3. `guard #available(iOS 26, *) else { … return }` refines the remainder of the enclosing scope, which keeps the happy path unindented. 4. The trailing `*` is mandatory; leaving it out fails with "must handle potential future platforms with '*'". `#available` is a condition clause, not a `Bool` expression. `!#available(…)` fails with "#available cannot be used as an expression, did you mean to use '#unavailable'?". ## Check at the call, or annotate the caller? The compiler's two fix-its are two different designs: - **Wrap the call** in `if #available` or `guard #available` when a sensible fallback exists right there: an older upload path, a simpler animation, a hidden button. - **Annotate the caller** with `@available(iOS 26, *)` when the whole function or type only makes sense on the new OS. The obligation moves up one level, to a caller that does have a fallback, such as the screen that decides whether to offer the feature at all. `@available` also applies to types and to extensions, including extensions that add a conformance, so a whole feature module can be fenced once instead of checked at every call. The cost of annotating is that every caller inherits the constraint; the cost of wrapping is a second code path that someone must keep tested on the older OS. ## `#unavailable` (Swift 5.6) SE-0290 added the inverted check for code that only needs the fallback: `if #unavailable(iOS 26) { showUpdateBanner() }`. Before it, the only way was an empty `if #available` branch followed by `else`, which reads like a mistake and usually needed a comment to survive review. The wildcard is implicit here, and writing it is an error: "platform wildcard '*' is always implicit in #unavailable". The refined availability belongs to the `else` branch. ## `anyAppleOS` (Swift 6.4) Apple's platforms share version numbers from 26.0 onward, and Swift 6.4 accepts `anyAppleOS` for those versions: - `@available(anyAppleOS 26, *)` and `if #available(anyAppleOS 26.0, *)` cover macOS, iOS, tvOS, watchOS and visionOS at version 26. - A platform-specific entry in the same list wins on its platform: `#available(anyAppleOS 26.0, macOS 26.4, *)` needs macOS 26.4 on a Mac and version 26 elsewhere. - The opt-in warning group `UseAnyAppleOSAvailability`, enabled with `-Wwarning`, suggests the short form where a per-platform list repeats one version. ## Compile time versus run time | Construct | Where it goes | Evaluated | Purpose | |---|---|---|---| | `@available(iOS 26, *)` | on a declaration | compile time | constrains every caller | | `if #available(iOS 26, *)` | statement condition | run time | branches on the running OS | | `if #unavailable(iOS 26)` | statement condition | run time | fallback-only branch | | `#if os(iOS)` | conditional compilation | compile time | picks code per platform, never per version | The last row is the classic mix-up: `#if os(iOS)` decides which code is compiled into the iOS binary at all, and it cannot see which iOS version the device runs. Only `#available` and `#unavailable` look at the running system.

  • Why does `if !#available(iOS 26, *)` not compile, and what replaces it?
    An availability condition is a special condition clause, not a `Bool` expression, so it cannot be negated. Swift 6.4 says "#available cannot be used as an expression, did you mean to use '#unavailable'?". Since Swift 5.6, `if #unavailable(iOS 26) { … }` runs fallback-only code; the `*` is implicit there.
  • What is the difference between `if #available(iOS 26, *)` and `#if os(iOS)`?
    `#if os(iOS)` is conditional compilation: it decides at build time whether code goes into the iOS binary at all, and it knows nothing about versions. `if #available(iOS 26, *)` is compiled into the binary and checks the running OS version at run time, refining which APIs the compiler lets you call in its body.
  • In Swift 6.4, how does anyAppleOS combine with a platform-specific version in one check?
    The platform-specific entry takes precedence when building for that platform. `if #available(anyAppleOS 26.0, macOS 26.4, *)` requires macOS 26.4 on a Mac and version 26 on iOS, tvOS, watchOS and visionOS. `anyAppleOS` only covers versions from 26.0, where the platforms share numbering.

  • #available is evaluated at compile time, like #if os(iOS).
  • Building with the newest SDK makes new APIs safe on older OS versions.
  • You can write if !#available(iOS 26, *) for the fallback branch.
  • @available(iOS 26, *) on a function checks the OS version at run time.
  • The trailing * means the check passes on every OS version.

Assumes Swift 6.4; #unavailable dates from Swift 5.6 (SE-0290) and the anyAppleOS platform name from Swift 6.4.