Xcode JSON xcproj: The New Project Format in Xcode 27.2

Every Xcode project has a file almost nobody reads on purpose: project.pbxproj. It's where merge conflicts come from when two people add files on different branches. Xcode 27.2 replaces it. The Xcode JSON xcproj format, a file named project.xcproj, stores the same project configuration as hierarchical JSON that people, diff tools and coding agents can actually work with.

This guide explains what the new file is, why Apple changed it, what it looks like, how to convert a project, and what to check before you switch: older Xcode versions, CI and third-party tools. It's based on Apple's documentation and release notes, Apple's open source format package, and write-ups by @sarunw and Artem Novichkov. The format is new in Xcode 27.2, and details can change between releases.

What is the new JSON .xcproj format in Xcode 27.2?

An .xcodeproj is a folder. Inside it is the project configuration file, along with other files such as shared schemes. Apple's article Updating your Xcode project configuration file format explains the change: in previous releases that file is a property list with a .pbxproj extension, and in Xcode 27.2 and later the default is "a smaller, hierarchical, self-describing JSON file with a .xcproj extension."

Three facts frame everything else:

• New projects get JSON by default. Projects you create in Xcode 27.2 and later use project.xcproj.
• Existing projects don't change on their own. Xcode 27 and later supports both formats, and you choose when to switch.
• The format is open source. Apple publishes it as xcode-project-format, a Swift package that models the file as typed values.

The Xcode 27.2 release notes summarize it in one line: the JSON-based format is "more readable, merge-friendly, and easier for coding agents to edit." As @sarunw put it when 27.2 arrived, Xcode 27.2 replaces .pbxproj with a new JSON .xcproj format.

Why is Apple replacing project.pbxproj?

The old format stores the project as a flat list of objects, each keyed by an opaque 24-character hexadecimal ID. Objects point at each other by those IDs. Adding one Swift file to a target typically touches several sections at once: a file reference, its place in a group, a build file entry and the target's Sources build phase. @sarunw describes the familiar result as one change "rewritten across three sections of project.pbxproj." When two branches each add a file, those scattered edits collide, and resolving them by hand means matching IDs across sections.

Build settings had a similar problem. Each configuration, such as Debug and Release, kept its own full block of settings, so one setting could appear in several places with different values.

Apple's documentation gives three reasons for the new format:

1. Reviewable diffs. Changes in the comparison view correspond to your actions in Xcode.
2. Fewer merge conflicts. The JSON format isolates configuration changes, so unrelated edits are less likely to touch the same lines.
3. Agent-friendly. It's easier for coding intelligence agents to edit the file for you.

Xcode 16's synchronized folders already removed per-file entries for files in those folders. @sarunw's write-up notes that the JSON format goes further, because targets, build phases, configurations and package references still used IDs in the property list.

What does a project.xcproj file look like?

Apple doesn't publish a full sample file in its documentation, but its open source package defines the top-level keys. They include default-configuration, configurations, localizations, files, targets, packages and build-settings. Here is a trimmed excerpt using those keys, with values from @sarunw's demo project. It isn't a complete file.

{
  "default-configuration": "Debug",
  "build-settings": {
    "DEBUG_INFORMATION_FORMAT[config=Debug]": "dwarf",
    "DEBUG_INFORMATION_FORMAT[config=Release]": "dwarf-with-dsym"
  }
}

A build setting is written once. When configurations need different values, the condition goes into the key, as with [config=Debug] above. Files are entries in the files tree, and each one carries its own target membership instead of being referenced from a separate build phase list. In @sarunw's sample, a file is a single line:

{ "path": "CatalogView.swift", "target-membership": [ "ToolbarPlacements/compile-sources" ] }

The size difference is noticeable. On @sarunw's demo project, a 300-line property list became 123 lines of JSON. Artem Novichkov's comparison found that adding the same Swift package took 24 lines in five places in project.pbxproj and 12 lines in two places in project.xcproj. Results will vary with your project, but the direction is consistent.

How do I convert an Xcode project to JSON xcproj?

Commit your work first, so the conversion is a clean, separate change. Then, in Xcode 27.2:

1. Select the project at the top of the Project navigator.
2. Open the File inspector.
3. Under Project Document, choose JSON from the Project Format pop-up menu.
4. If a dialog appears, click Continue.

Inside the .xcodeproj folder, project.pbxproj is removed and project.xcproj is added. Apple notes that if you use source control, you can undo the switch by discarding those two file changes. Schemes and other files in the bundle aren't part of the change.

For scripts and large repositories, Artem Novichkov reports that xcodebuild in Xcode 27.2 can convert in both directions. He also found that the converted file replaces the original, which is another reason to commit first. Check xcodebuild -help on your machine, since this isn't in Apple's article.

xcodebuild -project Weather.xcodeproj -convert-project xcproj
xcodebuild -project Weather.xcodeproj -convert-project pbxproj

Which Xcode versions and tools can read .xcproj?

Apple's documentation says the .xcproj format is compatible with Xcode 27 and later, and the release notes say projects using it also open in earlier versions of Xcode 27. So a team on Xcode 27.0 or 27.1 can open a converted project, but the conversion option itself is in 27.2. Anyone on Xcode 26 or earlier needs the property list format, which @sarunw's write-up notes remains the choice for legacy Xcode versions.

Third-party support is still arriving. Tuist's XcodeProj library, which many tools build on, added "[Experimental] support Xcode 27.2's JSON project format (project.xcproj)" in its 9.17.0 release. We couldn't confirm support in XcodeGen or in CocoaPods' xcodeproj gem, so treat any tool that edits project.pbxproj as unsupported until its own release notes say otherwise. If you generate your project from a spec and don't commit it, the format matters less, as long as the generator keeps working.

Apple's package is the better path for your own tooling. It requires Swift 6.1 or later, builds on macOS 14 and later and on other platforms, and is licensed under Apache 2.0 with a Runtime Library Exception. Its README shows reading a project with XCSchema.Project:

import XcodeProjectFormat

func listTargets(in projectURL: URL) throws {
    let projectData = try Data(contentsOf: projectURL)
    let project = try XCSchema.Project(jsonRepresentation: projectData)
    for target in project.targets {
        print(target.name)
    }
}

How does xcproj help coding agents and CI?

@sarunw's summary of the change is that the JSON format is more human-readable and editable by coding intelligence agents, which matches Apple's own wording. An agent that adds a file or a package to a property list has to invent valid IDs and update every section that references them. With JSON, the edit is a small, local change you can review in a pull request.

Apple's package also ships xcprojformatter, a command-line tool built on the library. Artem Novichkov describes running it with xcrun xcprojformatter: it prints the file in a canonical form, and --update rewrites it in place. That makes a useful CI check, because a formatter diff shows any hand or agent edit that isn't in canonical form. Check xcrun xcprojformatter --help for the exact arguments your version accepts.

xcrun xcprojformatter --update MyApp.xcodeproj/project.xcproj
git diff --exit-code -- MyApp.xcodeproj/project.xcproj

He also found that the formatter silently drops keys it doesn't recognize, such as a misspelled key, so review what it changes rather than assuming it validates everything. The same applies after a merge conflict: resolve the JSON, run the formatter, and check that targets and packages still look right in Xcode.

Does the JSON project format matter for iPhone Duo apps?

Not for how your app runs. The project format only changes how Xcode stores your configuration; the app you build for iPhone or iPhone Duo is the same. It does matter for the work around it. Adapting an app for iPhone Duo means rebuilding with the iOS 27.1 SDK and often touching project settings across branches, which is exactly when merge conflicts in project.pbxproj show up.

It also pairs well with Xcode 27's built-in agent skills, which cover modern best practices and new APIs. As @sarunw notes, the former uikit-app-modernization skill is now app-resizability and adds iPhone Duo support. If you let an agent help with that work, a JSON project file keeps its changes small enough to review. Our guide to exporting Xcode 27 agent skills covers that side, and the iPhone Duo preparation checklist lists the app changes themselves.

Key takeaways

• Xcode 27.2 replaces project.pbxproj with project.xcproj, a smaller, hierarchical JSON file, for new projects by default.
• The JSON format makes diffs match your actions, isolates changes to reduce merge conflicts and is easier for coding agents to edit.
• Convert existing projects in the File inspector under Project Document; commit first so you can undo it.
• .xcproj opens in Xcode 27 and later. Keep the property list if anyone, or any CI machine, is on Xcode 26.
• Check generators, scripts and dependency managers that parse project.pbxproj before switching; Apple's open source package and xcprojformatter help with your own tooling.

When your project is in order, put it to work on the device: start with the iPhone Duo preparation checklist, and see what other developers have shipped on Built for the fold.