XcodeProj

XcodeProj is a library written in Swift for parsing and working with Xcode projects. It's heavily inspired by CocoaPods XcodeProj and xcode.

It reads and writes both the property list format in project.pbxproj and, experimentally, the JSON format in project.xcproj that Xcode 27.2 introduced, through the same API. See the JSON project format.

---

• XcodeProj
  • Projects Using XcodeProj
  • Installation
    • Swift Package Manager
    • Scripting
  • The JSON project format (experimental)
  • References 📚
  • Contributing
  • License
  • Contributors ✨

Projects Using XcodeProj

If you are also leveraging XcodeProj in your project, feel free to open a PR to include it in the list above.

Installation

Swift Package Manager

Add the dependency in your Package.swift file:

let package = Package(
    name: "myproject",
    dependencies: [
        .package(url: "https://github.com/tuist/XcodeProj.git", .upToNextMajor(from: "8.12.0")),
    ],
    targets: [
        .target(
            name: "myproject",
            dependencies: ["XcodeProj"]),
        ]
)

Scripting

Using swift-sh you can automate project-tasks using scripts, for example we can make a script that keeps a project’s version key in sync with the current git tag that represents the project’s version:

#!/usr/bin/swift sh
import Foundation
import XcodeProj  // @tuist ~> 8.8.0
import PathKit

guard CommandLine.arguments.count == 3 else {
    let arg0 = Path(CommandLine.arguments[0]).lastComponent
    fputs("usage: \(arg0) <project> <new-version>\n", stderr)
    exit(1)
}

let projectPath = Path(CommandLine.arguments[1])
let newVersion = CommandLine.arguments[2]
let xcodeproj = try XcodeProj(path: projectPath)
let key = "CURRENT_PROJECT_VERSION"

for conf in xcodeproj.pbxproj.buildConfigurations where conf.buildSettings[key] != nil {
    conf.buildSettings[key] = newVersion
}

try xcodeproj.write(path: projectPath)

You could then store this in your repository, for example at scripts/set-project-version and then run it:

$ scripts/set-project-version ./App.xcodeproj 1.2.3
$ git add App.xcodeproj
$ git commit -m "Bump version"
$ git tag 1.2.3

Future adaption could easily include determining the version and bumping it automatically. If so, we recommend using a library that provides a Version object.

The JSON project format (experimental)

[!WARNING] This support is experimental. Xcode 27.2 is the first release that writes the format, so the mapping has only been verified against Apple's own library and hand written projects. Expect the details to move, and check a converted project before committing it.

Xcode 27.2 can store a project as JSON in project.xcproj rather than as a property list in project.pbxproj. XcodeProj reads and writes both through the same PBXProj object graph, so existing code keeps working.

let project = try XcodeProj(path: "MyApp.xcodeproj")
print(project.projectFormat)  // .pbxproj or .xcproj

// Writing keeps the format the project was read in.
try project.write(path: "MyApp.xcodeproj")

// Converting is one argument.
try project.write(path: "MyApp.xcodeproj", format: .xcproj)

The JSON project format covers object identifiers, how build settings map between the two shapes, and what a conversion does not carry over.

References 📚

• Xcode Project File Format
• pbexplorer
• pbxproj identifiers
• mob-pbxproj
• Xcodeproj
• Nanaimo
• Facebook Buck

Contributing

1. Git clone the repository git@github.com:tuist/xcodeproj.git.
2. Open Package.swift with Xcode.

License

XcodeProj is released under the MIT license. See LICENSE for details.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!