Xcode 27.2: What Developers Need to Know (Including the New JSON Project Format)

Xcode 27.2 is a point release, but it ships one change that will affect almost every team sooner or later: a new JSON-based project file that replaces the old project.pbxproj. The rest of the release is a mix of small features, a solid batch of Device Hub and Previews fixes, and a few known issues you should know about before you upgrade your CI machines.

This post walks through what matters, in order of how likely it is to affect your day.

Note: This is based on Apple's Xcode 27.2 release candidate notes. Details can still shift before the final release, so check the official notes linked at the end before making team-wide decisions.

TL;DR

• Requirements: macOS Tahoe 26.6 or later. Ships with Swift 6.4 and the 27.2 SDKs for iOS, iPadOS, macOS, tvOS, watchOS, and visionOS.
• Biggest change: a new JSON project format (.xcproj) that is readable, diff-friendly, and much less prone to merge conflicts. It is the default for new projects and opt-in for existing ones.
• Compatibility gotcha: .xcproj projects open in Xcode 27 and later only. Anyone still on Xcode 26 cannot open them.
• Coding Assistant: a new GetCodeCoverage MCP tool so agents can read coverage from your latest test run.
• Previews: a new Display group in the canvas overrides picker for alternate displays, plus several reliability fixes.
• Device Hub: many input-related fixes, including iOS 17 simulator input.
• Watch out for: a deployment-target bug in the non-iOS SDKs, Mac Catalyst compile errors with iOS 27.1-only APIs, and a few simulator quirks (workarounds below).

Requirements and platform support

Item	Xcode 27.2
Host macOS	macOS Tahoe 26.6 or later
Swift	6.4
SDKs	iOS, iPadOS, tvOS, watchOS, macOS, visionOS 27.2
On-device debugging	iOS 17+, tvOS 17+, watchOS 10+, visionOS

If your build machines are still on an older macOS, update them first. That is usually the step that blocks CI upgrades, not Xcode itself.

Apple also notes that the iOS SDK and simulator support for iPhone Duo come from a separate download on the Apple Developer downloads page, so grab that if you are targeting the new hardware.

The headline: a JSON project format (.xcproj)

If you have ever resolved a merge conflict in project.pbxproj, this is the section you care about.

What changed

An .xcodeproj bundle has always contained a project configuration file called project.pbxproj. It is an old-style property list full of generated 24-character object IDs, cross-references, and comments. It works, but it is hard to read, hard to review, and famously painful to merge.

Starting in Xcode 27.2, Xcode can store that configuration as a JSON file named project.xcproj instead. According to Apple, the new file is:

• Smaller and hierarchical. Structure is nested rather than a flat table of objects pointing at each other by ID.
• Self-describing. You can open it and understand what you are looking at.
• Easier to review. Changes in a diff line up with what you actually did in Xcode, so a pull request that adds one file shows a small, readable change.
• Less conflict-prone. Configuration changes are more isolated, so two people adding files to the same target are far less likely to collide.
• Agent-friendly. Coding assistants (Xcode's own or external ones over MCP) can edit it reliably instead of guessing at pbxproj IDs.

The outer .xcodeproj folder stays the same. Only the file inside it changes:

Before:
MyApp.xcodeproj/
  project.pbxproj
  project.xcworkspace/
  xcshareddata/

After:
MyApp.xcodeproj/
  project.xcproj        <- new JSON file
  project.xcworkspace/
  xcshareddata/

So scripts and tools that just point at MyApp.xcodeproj (for example xcodebuild -project MyApp.xcodeproj) keep the same path. Tools that open and parse project.pbxproj directly are a different story; more on that below.

Is it the default?

• New projects created in Xcode 27.2 use the JSON format by default.
• Existing projects keep using project.pbxproj until you switch them.

Xcode 27 and later understands both formats, so there is no forced migration.

How to convert an existing project

1. Open the project in Xcode 27.2.
2. Select the project in the Project navigator.
3. Open the File inspector (right sidebar).
4. Under Project Document, set Project Format to JSON.
5. If a confirmation dialog appears, click Continue.

Xcode removes project.pbxproj and adds project.xcproj inside your .xcodeproj.

How to undo it

If you use source control, reverting is simple: discard the change that deleted project.pbxproj and added project.xcproj. For example, with Git:

git restore MyApp.xcodeproj/project.pbxproj
rm MyApp.xcodeproj/project.xcproj

My recommendation: do the conversion as its own commit with nothing else in it. That makes it trivial to review and trivial to roll back.

Compatibility: read this before converting a shared project

This is the part that can bite a team.

• .xcproj projects open in Xcode 27 and later, including earlier Xcode 27.x releases.
• They do not open in Xcode 26 or earlier.

Before converting a shared repository, check:

• Every developer on the team is on Xcode 27 or later.
• Every CI runner (GitHub Actions, Xcode Cloud, Bitrise, self-hosted, and so on) uses an Xcode 27 image.
• Release branches that still build with an older Xcode are not affected. Convert on your main branch, not on a maintenance branch that must keep building with Xcode 26.

Check your tooling

A lot of iOS tooling reads or writes project.pbxproj directly. Common examples include project generators, dependency managers that patch your project, release automation, and linters that inspect build settings or file membership. Until those tools announce support for .xcproj, assume they may not understand it.

Practical approach:

1. Convert on a branch.
2. Run your full pipeline: dependency install, build, tests, signing, and any scripts that touch the project.
3. Only merge once everything passes.

If you generate your project from a spec (for example with a project generator), you may not need to convert at all; keep generating whatever format your tool supports and revisit later.

Apple open sourced the format

Apple published the format as an open source Swift package, xcode-project-format (Apache 2.0). It models the whole project (targets, groups, file references, build phases, build rules, and more) as typed Swift values under an XCSchema namespace, and it includes a small CLI called xcprojformatter.

That matters because tool authors no longer need to reverse-engineer the format. If you maintain internal scripts that poke at project files, this is the library to build on.

Add it to a package:

dependencies: [
    .package(url: "https://github.com/apple/xcode-project-format/", from: "0.1.0")
]

A quick script that prints every target in a project:

import Foundation
import XcodeProjectFormat

let url = URL(fileURLWithPath: "MyApp.xcodeproj/project.xcproj")
let data = try Data(contentsOf: url)
let project = try XCSchema.Project(jsonRepresentation: data)

for target in project.targets {
    print(target.name)
}

The package requires Swift 6.1 or later and macOS 14 or later, and also builds on non-Apple platforms, which is handy for Linux-based CI checks.

Should you switch now?

Switch now if:

• Your whole team and CI are already on Xcode 27.
• You regularly fight project.pbxproj merge conflicts.
• You use coding agents to add files, targets, or build settings.

Wait if:

• Anyone still needs to open the project in Xcode 26.
• You depend on tools that edit the project file and have not confirmed .xcproj support.
• You generate the project from a spec and the generator does not output .xcproj yet.

Coding Assistant: code coverage over MCP

Xcode 27.2 adds a GetCodeCoverage MCP tool. It reports code coverage from your most recent test result, and you can filter it by target or by file.

Why it is useful: an agent can now run your tests, check which lines are not covered, and write tests for exactly those gaps, all without you exporting coverage reports by hand. If you use an external agent connected to Xcode over MCP, it gets access to this tool too.

Related fix: the RenderPreview MCP tool now returns the list of available render destinations and lets the caller choose which one to render on. Agents that render SwiftUI previews can now target a specific device instead of whatever the default happens to be.

Previews

New: the canvas overrides picker now has a Display group, so you can preview content on a device's alternate display. If you are building for hardware with more than one screen (such as iPhone Duo), this is how you check the second display without running the app.

Fixed:

• Previews no longer fail in source files that use Windows-style CRLF line endings. If you share code with Windows-based tooling or have files that came through a cross-platform repo, this one may have been silently breaking your canvas.
• If another user account on the same Mac owns the Previews JIT directory, Xcode now shows a clear error with recovery steps instead of a vague failure. Shared build Macs and multi-user setups hit this.
• Clearer error when the selected platform cannot show a preview's content.
• Selecting a preview from a preview group's thumbnail grid on macOS now reliably opens the right one.

Device Hub and Simulator fixes

Device Hub got a lot of input-handling fixes. If you mirror and control devices or simulators from Xcode, most of these will feel like things just started working:

• Keyboard and mouse input now works for simulators running older OS versions (before iOS 18, tvOS 18, watchOS 11, and visionOS 2).
• Device Hub now supports input to iOS 17 simulators.
• Device Hub no longer stops sending touch and button input to a connected device after it has been idle for a while.
• Disconnecting a physical device while Simulate Hardware Keyboard was on no longer leaves it stuck in hardware keyboard mode (which used to hide the software keyboard for up to two minutes).
• Modifier keys (Shift, Control, Option, Command) now go to the right device when multiple device windows are open.
• Holding Escape now exits keyboard capture mode.
• Deleted simulator runtimes are now fully removed, instead of reappearing after a reboot.

Known issues to plan around

These are the ones most likely to cost you time.

SDK deployment target bug (macOS, watchOS, tvOS, visionOS)

The macOS, watchOS, tvOS, and visionOS SDKs in Xcode 27.2 incorrectly list 27.1 as a valid deployment target. If you pick it, builds and other features may behave unexpectedly. Mac Catalyst builds with a 27.1 or 27.2 deployment target may also be unable to use newly introduced APIs.

What to do: do not set your deployment target to 27.1 on those platforms with this Xcode. Stick with the target you already had, or 27.2 if you need the new APIs and are not building for Catalyst.

Mac Catalyst: compile errors with iOS 27.1-only APIs

Projects that use APIs specific to iOS 27.1 can fail to compile for Mac Catalyst with errors like "undeclared identifier", "has no member", or "cannot find".

Workaround: wrap the affected code in a compile-time check.

Swift:

#if !targetEnvironment(macCatalyst)
// iOS 27.1-only API usage here
#endif

Objective-C:

#if !TARGET_OS_MACCATALYST
// iOS 27.1-only API usage here
#endif

Simulator runtime shows as unavailable after reinstalling

If you delete a simulator runtime and reinstall it, Xcode may still show it as unavailable.

Workaround: restart the CoreSimulator service.

killall -9 com.apple.CoreSimulator.CoreSimulatorService

Device Hub crashes when selecting a Vision Pro simulator without a runtime

If no visionOS runtime is installed, selecting a Vision Pro simulator in Device Hub can make Device Hub quit.

Workaround: install the matching visionOS runtime from Xcode, or delete that simulator device.

Smaller ones

• Simulate Memory Warning (Device menu) does not work. If you test memory-pressure handling, trigger it another way for now.
• iPhone Duo screenshots and recordings can come out black for up to a few minutes after the device boots. Wait a bit before capturing App Store screenshots.
• Cloning a 27.2 simulator device can fail due to incorrect file permissions. If you script simulator cloning for parallel tests, watch for this.
• Accessibility tools (VoiceOver, Accessibility Inspector) cannot read screen content on iPhone Duo inside Device Hub. Test accessibility on a physical device or a regular simulator window.
• CarPlay in Device Hub needs a USB-connected device. Network-connected devices and the iOS Simulator are not supported for CarPlay.

Upgrade checklist

1. Update build Macs to macOS Tahoe 26.6 or later.
2. Install Xcode 27.2 side by side with your current Xcode first, and run your full test suite.
3. If you target iPhone Duo, download its SDK and simulator support separately.
4. Check your non-iOS deployment targets are not set to 27.1.
5. If you ship Mac Catalyst, look for iOS 27.1-only API usage and add #if !targetEnvironment(macCatalyst) guards.
6. Decide on .xcproj: convert only when the whole team and CI are on Xcode 27, and do it as a standalone commit.
7. If you use coding agents, try GetCodeCoverage to have them target untested code.

Wrapping up

Most of Xcode 27.2 is polish: better Device Hub input, sturdier Previews, and a couple of handy MCP tools for agents. The JSON project format is the real story. It fixes one of the oldest pain points in Apple development, and because it is open source, the tooling ecosystem can catch up quickly. Give your CI and tools a test run on a branch, and once everything is green, the days of untangling project.pbxproj conflicts are over.

References

• Xcode 27.2 Release Notes