> Switching Your Xcode Project to the New JSON Format (.xcproj)

If you've ever resolved a merge conflict inside project.pbxproj, you know the pain. Two teammates each add a file to the project, git throws a conflict in a wall of hex identifiers and nested plist syntax, and you're left squinting at isa = PBXBuildFile entries trying to figure out which side to keep. That file format dates back to NeXT, and it was never designed to be read by humans, let alone merged by them.

Xcode 27.2 finally does something about it. New projects now use a JSON-based configuration file with an .xcproj extension instead of the old .pbxproj property list, and you can convert existing projects with a single setting. Apple documents the change in Updating your Xcode project configuration file format.

What Actually Changed

A quick refresher on what lives where. The .xcodeproj bundle you see in Finder is actually a folder holding your project's configuration along with workspace data and schemes. The heart of it has always been project.pbxproj, an old-style property list that describes every file reference, target, build phase, and build setting in your project.

In Xcode 27.2 and later, the default is a JSON file with an .xcproj extension instead. Apple describes the new format as smaller, hierarchical, and self-describing, and it's an open format rather than a NeXT-era artifact. Xcode 27 and later reads both formats, so nothing forces you to convert. Old projects keep working exactly as they did.

The practical wins show up in source control. Because the JSON format isolates configuration changes, a diff of the project file actually corresponds to what you did in Xcode: add a file, and the diff shows a file being added, not four scattered edits across reference sections. That same isolation means two people touching different parts of the project are far less likely to conflict at all. And when a conflict does happen, you're resolving readable JSON instead of guessing at opaque identifiers.

Apple also calls out one more motivation directly: the format is easier for coding intelligence agents to edit. If you use Claude Code or Xcode's own intelligence features to manage your project, a self-describing JSON file is something an agent can modify reliably, which was never really true of pbxproj.

How to Convert an Existing Project

The switch is a single setting. Select the project itself at the top of the Project navigator, open the File inspector on the right, and find the Project Format pop-up under the Project Document section. Choose JSON. If Xcode shows a confirmation dialog, click Continue.

That's the whole migration. On disk, Xcode deletes the project.pbxproj file inside your .xcodeproj bundle and writes the equivalent .xcproj JSON file in its place. Commit that change like any other, and it's worth glancing at the diff once just to see the difference in readability for yourself.

If you change your mind, undoing it is just as simple as long as you use source control: discard the changes inside the .xcodeproj folder, which restores the deleted .pbxproj file and drops the new .xcproj one. You can also flip the Project Format pop-up back at any time.

Before You Flip the Switch on a Team Project

The format is compatible with Xcode 27 and later, so the first question is whether everyone on the team, including your CI machines, has moved to Xcode 27. Anyone on an older release won't be able to open the project once it's converted.

The second thing to check is tooling. A lot of the iOS ecosystem reads or writes project.pbxproj directly: CocoaPods through the xcodeproj gem, fastlane actions that bump versions or tweak settings, project generators, and various scripts teams accumulate over the years. Those tools need to understand the new format before they'll work with a converted project, and as of Xcode 27.2's release that support is still rolling out. If your build pipeline touches the project file anywhere, test the conversion on a branch and run the full pipeline before merging it.

For a solo project or one with a plain Xcode-only setup, there's little reason to wait. The conversion is instant, reversible, and every project diff you review afterward gets easier to read.

Wrapping Up

The pbxproj format hung around for decades because replacing it was risky and the pain was tolerable. With Xcode 27.2, Apple has done the replacement for you: an open JSON format that produces sane diffs, avoids most merge conflicts, and plays well with AI tooling. New projects get it by default, and converting an old one is a pop-up menu away. Check your Xcode versions and your tooling first, then make the switch on a branch and enjoy never manually merging a PBXBuildFile section again.