Xcode 27.1 builds on the 27 line with a new Swift version, refreshed SDKs and a handful of Previews and Simulator additions. The notes are short, but two of the listed known issues will break a build or remove a run destination the moment you add Mac Catalyst to a project that targets iOS 27.1.
This breakdown sticks to what Apple published in the Xcode 27.1 release notes.
What’s new
- Swift 6.4 ships in the box. The toolchain moves forward a language version, so any package or target that pins a Swift tools version should be re-checked after updating. If your project builds on CI with a specific Swift release, that pin now needs attention.
- SDKs for the 27 wave. Xcode 27.1 includes SDKs for iOS 27.1, iPadOS 27, tvOS 27, watchOS 27, macOS 27 and visionOS 27. Note the iOS side is 27.1 while the other platforms in this list are 27 — build settings and deployment targets should match the platform you actually ship on.
- Debugging support on older OS versions. On-device debugging works down to iOS 17 and later, tvOS 17 and later, watchOS 10 and later, and visionOS. That range matters if you keep a spare device on an older release for testing release builds.
- Host requirement: macOS Tahoe 26.6 or later. Xcode 27.1 will not run on anything older. Before you update, confirm the Macs on your team and your CI runners are on Tahoe 26.6 at minimum.
- Previews: display group in the canvas overrides picker. The canvas overrides picker now has a Display group, which lets you preview content on a device’s alternative display. If you are building for a device with a second screen, you no longer have to run on hardware to see how the layout behaves there.
Known issues and workarounds
Mac Catalyst: compile errors when using iOS 27.1 APIs
Projects that use APIs specific to iOS 27.1 fail to compile for Mac Catalyst. The errors surface as undeclared identifier, not found, has no member, cannot find and similar messages — the tell is that the same code compiles cleanly for iOS but not for Catalyst. (185924957)
Workaround from the notes: isolate the affected code behind build-time conditionals.
#if !targetEnvironment(macCatalyst)
// iOS 27.1-only API use goes here
#endif
In Objective-C the equivalent guard is #if !TARGET_OS_MACCATALYST.
Because the guard is compile-time, anything inside the #if block is simply absent on Catalyst. Wrap the call site and provide a Catalyst fallback, rather than wrapping only the declaration — otherwise you trade a compile error for a missing-symbol error at the call site.
No Mac Catalyst run destination for iOS 27.1 targets
A project that targets iOS 27.1 shows no Mac Catalyst run destination at all, which usually reads as “My Mac” quietly disappearing from the scheme picker. (187046347)
Workaround from the notes: add a Mac Catalyst 27.0 minimum deployment in the target settings. Set it explicitly rather than inheriting the iOS deployment target; the 27.0 value is what restores the destination.
Simulator: slow first launch
The initial Simulator launch can take several minutes. (187708500)
There is no workaround listed. Practically, start the Simulator early rather than waiting for the first Run, and avoid scripting a workflow that assumes the first boot is as fast as later ones.
StandBy missing in the iPhone Duo Simulator runtime
StandBy is unavailable in the iPhone Duo Simulator runtime. (187708663)
No workaround is given. Test StandBy on a physical device or on a non-Duo simulator runtime.
App extensions can’t run or debug in the iPhone Duo runtime
Running and debugging most app extensions is unavailable in the iPhone Duo Simulator runtime. (187708767)
No workaround is listed. If you are working on a widget, share extension or similar target, pick a different simulator runtime for the debugging session.
Camera capture and dual displays in the iPhone Duo simulator
In the iPhone Duo simulator, an app using CameraCaptureAccessory can use both displays at the same time without an active camera capture session. (190155353)
This is noted as a known issue rather than something with a workaround, so treat dual-display behaviour around camera capture in the simulator as untrustworthy and verify on hardware.
Resolved issues worth knowing
The Xcode 27.1 release notes do not list any resolved issues. If you were waiting on a fix from an earlier 27.x seed, this build’s notes give you nothing to confirm it against — check the issue in your own project rather than assuming it landed.
Should you update?
Update if you need to build against the iOS 27.1 SDK, you want Swift 6.4, or you are actively previewing layouts on an alternative display and want the new Display group in the canvas overrides picker. The Mac Catalyst issues both have documented workarounds, so a Catalyst project is not blocked — just plan for the two edits below.
Consider waiting if your CI fleet is not yet on macOS Tahoe 26.6 or later, since Xcode 27.1 simply will not install and run there. The same applies if your test plan depends on running extensions or testing StandBy in the iPhone Duo Simulator runtime, or on a fast cold simulator boot.
What to check in your project before you switch the default Xcode:
- The Swift tools version in every
Package.swiftand any CI job that pins a Swift release — Swift 6.4 is new here. - The Mac Catalyst minimum deployment target. If a target builds for Catalyst and targets iOS 27.1, set Mac Catalyst to 27.0 explicitly.
- Every call into an iOS 27.1-only API from code shared with Catalyst, and whether it needs a
#if !targetEnvironment(macCatalyst)guard plus a fallback. - Which simulator runtime your extension targets use for debugging, so nobody loses a morning to a missing run destination.
- Your macOS deployment target against the macOS 27 SDK.
FAQ
Does Xcode 27.1 run on my Mac?
Xcode 27.1 requires a Mac running macOS Tahoe 26.6 or later. Check your CI runners and any older machines before you make it the default toolchain.
Why does my iOS 27.1 project have no Mac Catalyst run destination?
The release notes list this as a known issue (187046347). Add a Mac Catalyst 27.0 minimum deployment in the target settings — the destination reappears once that value is set.
Why does code that compiles for iOS fail with has no member or undeclared identifier under Mac Catalyst?
If the code uses APIs specific to iOS 27.1, Catalyst builds fail. This is a known issue (185924957). Wrap the affected code in #if !targetEnvironment(macCatalyst) — or #if !TARGET_OS_MACCATALYST in Objective-C — and supply a fallback for the Catalyst path.