📝 Read, update and write your Xcode projects
Latest commit 064eef4 Nov 4, 2018
Failed to load latest commit information.
.circleci Specify project Oct 12, 2018
.github Rename usages of xpm to tuist Jul 23, 2018
Assets Remove header Apr 30, 2018
Fixtures Adjusting sorting and writing tests. Sep 26, 2018
Sources/xcodeproj Adds project reference format setting to PBXOutputSettings following … Oct 29, 2018
Templates Fix issue with sourcery May 11, 2018
Tests Adds project reference format setting to PBXOutputSettings following … Oct 29, 2018
docs Version 6.3.0 Oct 18, 2018
xcodeproj-Carthage.xcodeproj Add Carthage compatibility Oct 12, 2018
xcodeproj-Carthage.xcworkspace Add Carthage compatibility Oct 12, 2018
.editorconfig [jazzy] Add documentation Jul 1, 2017
.gitattributes add union merge for CHANGELOG Sep 23, 2018
.gitignore Rename xcproj to xcodeproj Apr 30, 2018
.jazzy.yaml Update RELEASE steps and regenerate documentation Oct 5, 2018
.rspec [danger-carthage] Add a Danger plugin to check if the Carthage projec… Dec 13, 2017
.ruby-version Bump Ruby version to 2.5.1 May 10, 2018
.swift-version Add Slack badge and .swift-version file Sep 20, 2018
.swiftlint.yml Fix swiftlint issues Aug 8, 2018
CHANGELOG.md Add to changelog Oct 29, 2018
CODE_OF_CONDUCT.md Rename usages of xpm to tuist Jul 23, 2018
CONTRIBUTING.md Rename usages of xpm to tuist Jul 23, 2018
Cartfile Add Carthage compatibility Oct 12, 2018
Cartfile.resolved Add Carthage compatibility Oct 12, 2018
Gemfile Use CocoaPods 1.6.0.beta.1 Oct 12, 2018
Gemfile.lock Use CocoaPods 1.6.0.beta.1 Oct 12, 2018
Info.plist Add Carthage compatibility Oct 12, 2018
LICENSE.md Rename xcproj to xcodeproj Apr 30, 2018
Package.resolved Change release process Oct 12, 2018
Package.swift Add podspec Oct 12, 2018
Project.swift Add Carthage compatibility Oct 12, 2018
README.md Update README.md Nov 5, 2018
RELEASE.md Version 6.2.0 Oct 12, 2018
Rakefile Version 6.2.0 Oct 12, 2018
sourcery.yml Rename folder Sep 7, 2018
xcodeproj.podspec Version 6.3.0 Oct 18, 2018



CircleCI branch Swift Package Manager Release Code Coverage Slack License

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

This project is a fork and evolution from xcproj

Projects Using xcodeproj

Project Repository
Tuist github.com/tuist/tuist
Sourcery github.com/krzysztofzablocki/Sourcery
ProjLint github.com/JamitLabs/ProjLint
XcodeGen github.com/yonaskolb/XcodeGen

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


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: "6.2.0")),
    targets: [
            name: "myproject",
            dependencies: ["xcodeproj"]),


Only macOS

# Cartfile
github "tuist/xcodeproj" ~> 6.2.0


pod 'xcodeproj', '~> 6.2.0'

Migration Guides

xcodeproj 6

xcodeproj 6 is the final step towards hiding the Xcode project implementation details. One of those details was the object unique identifiers, which you used to manage yourself with previous versions. Now, xcodeproj does it for you, so you don't have to pass them around to set dependencies between objects.

This improvement makes the API easier, safer and more convenient, but at the cost of introducing some breaking changes in the library. If want to migrate your project to use xcodeproj 6, these are the things that you should look at:

  • PBXObjectReference is an internal class now. Object references to other objects are attributes with the type of the object that is being referred. For example, a XCConfigurationList object has an attribute buildConfigurations of type XCBuildConfiguration. Adding a new configuration is as easy as calling list.buildConfigurations.append(config).
  • Note that object references have different types of optionals based on the type of attribute:
    • Implicitly unwrapped optional: When the attribute is required by Xcode. Example
    • Explicitly unwrapped optional: When the attribute is optional by Xcode. Example
  • PBXObjects has also been made internal. It was exposed through the attribute objects on the PBXProj class. If you used to use this class for adding, removing, or getting objects, those methods have been moved to the PBXProj class - Public helpers

And yes, in case you are wondering, it fully supports Xcode 10 🎉

xcodeproj 5

xcodeproj 5 is a major release with important changes in the API focused on making it more convenient, and simplify the references handling. This version hasn't been officially released yet but you can already start updating your project for the new version. These are the changes you'd need to make in your projects:

  • xcproj has been renamed to xcodeproj so you need to update all your import statements to use the new name.
  • There's no support for Carthage nor CocoaPods anymore, if you were using them for fetching xcodeproj, you can use the Swift Package Manager and manually setup the dependency.
  • We've replaced Path with AbsolutePath and RelativePath from the Swift Package Manager's Basic framework. You might need to change some of the usages to use the new type.
  • Reference attributes have been renamed to use the naming convention attributeReference where attribute is the name of the attribute. If you are interested in materializing the reference to get the object, objects provide convenient getters that you can use for that purpose. Those getters throw if the object is not found in the project.

There are some useful additions to the API that you can check out on the CHANGELOG.

One of those additions is an improvement on how references are managed. When new objects are added to the project, you get the object reference. The reference is an instance that should be used to refer that object from any other. The value of that reference is an implementation detail that has been abstracted away from you.


You can check out the documentation on the following link. The documentation is automatically generated in every release by using Jazzy from Realm.

References 📚


  1. Git clone the repository git@github.com:tuist/xcodeproj.git.
  2. Generate xcodeproj with swift package generate-xcodeproj.
  3. Open xcodeproj.xcodeproj.


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

Open source

Tuist is a proud supporter of the Software Freedom Conservacy

Become a Conservancy Supporter!