Swiftpack.co - Package - tuist/XcodeProj


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 by CocoaPods XcodeProj and xcode.

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 | | xspm | gitlab.com/Pyroh/xspm |

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


Only macOS

# Cartfile
github "tuist/xcodeproj" ~> 7.11.


pod 'xcodeproj', '~> 7.14.0


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 ~> 7.11.
import PathKit

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

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

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.

Documentation 📝

Want to start using XcodeProj? Start by digging into our documentation which will help you get familiar with the API and get to know more about the Xcode projects structure.

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!


Stars: 1206



7.14.0 - 2020-07-21 06:17:28


  • lastKnownFileType for .ttf and .sqlite files https://github.com/tuist/XcodeProj/pull/557 by @adamkhazi


  • Added selectedTests attribute to XCScheme.TestableReference https://github.com/tuist/XcodeProj/pull/559 by @ooodin

7.13.0 - 2020-07-14 04:50:49


  • Support on-demand-install-capable application https://github.com/tuist/XcodeProj/pull/554 by @d-date
  • Add RemotePath to RemoteRunnable https://github.com/tuist/XcodeProj/pull/555 by @kwridan

7.12.0 - 2020-06-24 05:41:03


  • Added LaunchAction.customLLDBInitFile and TestAction.customLLDBInitFile attributes https://github.com/tuist/xcodeproj/pull/553 by @polac24

7.11.1 - 2020-06-03 09:29:01


  • Added platformFilter to the PBXTargetDependency https://github.com/tuist/XcodeProj/pull/546 by @tomaslinhart

7.11.0 - 2020-06-02 08:36:33


  • Point XcodeProjCExt to version 0.1.0 https://github.com/tuist/XcodeProj/pull/540 by @khoi


  • Added useTestSelectionWhitelist attribute to XCScheme.TestableReference https://github.com/tuist/xcodeproj/pull/516 by @basvankuijck.


  • "Products" group has the same ID for any project https://github.com/tuist/XcodeProj/issues/538 by @damirdavletov

7.8.0 - 2020-04-03 06:32:11


  • Added PathRunnable to the LaunchAction to allow running any executable https://github.com/tuist/XcodeProj/pull/521 by @vytis


  • Make PBXProject.targetAttributes non optional again and fix equality https://github.com/tuist/XcodeProj/pull/519 by @yonaskolb

7.10.0 - 2020-04-02 15:52:03


  • Optimize bottlenecks https://github.com/tuist/XcodeProj/pull/529 by @michaeleisel

7.9.0 - 2020-03-25 12:28:01


  • Remove Tapestries folder for tapestry 0.0.5 version https://github.com/tuist/XcodeProj/pull/523 by @fortmarek


  • Code Coverage Targets and Additional Options Scheme Instability https://github.com/tuist/XcodeProj/pull/522 by @adamkhazi
  • Fix XCWorkspace Equatable https://github.com/tuist/XcodeProj/pull/524 by @adamkhazi

7.7.0 - 2020-01-29 16:13:29


  • Ensure references to products in external projects are generated with deterministic UUIDs https://github.com/tuist/XcodeProj/pull/518 by @evandcoleman

7.6.0 - 2020-01-24 05:48:48


  • Breaking Make PBXProject.targetAttributes optional https://github.com/tuist/XcodeProj/pull/517 by @pepibumur


  • Remove "Shell" Carthage dependency from carthage xcode project as it's no longer used https://github.com/tuist/XcodeProj/pull/507 by @imben123


  • Added com.apple.product-type.xcframework to PBXProductType. https://github.com/tuist/XcodeProj/pull/508 by @lakpa
  • Added askForAppToLaunch parameter to LaunchAction and ProfileAction. https://github.com/tuist/XcodeProj/pull/515 by @YutoMizutani
  • Added "ENABLE_PREVIEWS" to target application build settings https://github.com/tuist/XcodeProj/pull/511 by @fortmarek

7.5.0 - 2019-11-13 10:35:12


  • Provide default build settings for unit and ui test targets https://github.com/tuist/XcodeProj/pull/501 by @kwridan
  • Remove "Shell" Carthage dependency from project manifest as it's no longer used https://github.com/tuist/XcodeProj/pull/505 by @kwridan

7.4.0 - 2019-11-09 11:28:15


  • Update list of recognized file extensions https://github.com/tuist/XcodeProj/pull/500 by @dflems

7.3.0 - 2019-11-06 09:50:41


  • Update BuildSettingsProvider to include extension settings https://github.com/tuist/XcodeProj/pull/497 by @kwridan
  • Remove the dependency with the Swift Package Manager https://github.com/tuist/XcodeProj/pull/499 by @elliottwilliams

7.2.2 - 2019-10-30 08:29:03


  • Make test plans deserialise correctly https://github.com/tuist/XcodeProj/pull/496 by @adamkhazi

7.2.1 - 2019-10-29 11:57:18


  • Make test plans optional by https://github.com/tuist/XcodeProj/commit/c15034948a2a132bf559f14d3c6b4d1b73749663 @pepibumur

7.2.0 - 2019-10-27 19:51:09


  • Added support for Xcode 11 test plans https://github.com/tuist/XcodeProj/pull/491 by @maniramezan


  • Add remote Swift packages to the Frameworks build phase https://github.com/tuist/XcodeProj/pull/487 by @kwridan
  • System library added to a group has empty path https://github.com/tuist/XcodeProj/pull/488 by @damirdavletov
  • Fix Products group serialisation with temporary ids https://github.com/tuist/XcodeProj/pull/489 by @damirdavletov

7.1.0 - 2019-09-27 10:17:22


  • Add onlyGenerateCoverageForSpecifiedTargets parameter to TestAction https://github.com/tuist/XcodeProj/pull/473 by @kateinoigakukun
  • Added support for PBXTargetDependency.product https://github.com/tuist/XcodeProj/pull/481 by @yonaskolb
  • Xcode 11 support

7.0.1 - 2019-09-12 19:26:00


  • Update BuildSettingProvider to return LD_RUNPATH_SEARCH_PATHS as Array https://github.com/tuist/xcodeproj/pull/463 by @marciniwanicki
  • Update Project.swift to make it compatible with tuist 0.17.0 https://github.com/tuist/xcodeproj/pull/469 by @marciniwanicki


  • Adding support for adding local Swift packages https://github.com/tuist/XcodeProj/pull/468 by @fortmarek
  • Adding additional lastKnownFileTypes https://github.com/tuist/xcodeproj/pull/458 by @kwridan
  • Adding possibility to create variant group for referencing localized resources https://github.com/tuist/xcodeproj/pull/462 by @timbaev


  • Duplication of packages https://github.com/tuist/XcodeProj/pull/470 by @fortmarek

7.0.0 - 2019-06-25 16:26:48


  • Breaking Change the UUID generation logic to generate ids with a length of 24 https://github.com/tuist/xcodeproj/pull/432 by @pepibumur.
  • Breaking Renamed module from xcodeproj to XcodeProj https://github.com/tuist/xcodeproj/pull/398 by @pepibumur.
  • Add override flag to PBXGroup.addFile(at:,sourceTree:,sourceRoot:) https://github.com/tuist/xcodeproj/pull/410 by @mrylmz
  • Rename some internal variables to have a more representative name https://github.com/tuist/xcodeproj/pull/415 by @pepibumur.


  • Breaking Add SWIFT_COMPILATION_MODE and CODE_SIGN_IDENTITY build settings, remove DEBUG flag for Release https://github.com/tuist/xcodeproj/pull/417 @dangthaison91
  • Breaking Added throwing an error in case group path can't be resolved by @damirdavletov
  • Breaking Added remote project support to PBXContainerItemProxy by @damirdavletov
  • Breaking Add support for RemoteRunnable https://github.com/tuist/xcodeproj/pull/400 by @pepibumur.
  • Breaking Swift 5 support https://github.com/tuist/xcodeproj/pull/397 by @pepibumur.
  • Added com.apple.product-type.application.watchapp2-container to PBXProductType. https://github.com/tuist/xcodeproj/pull/441 by @leogdion.
  • Add BatchUpdater to quickly add files to the group https://github.com/tuist/xcodeproj/pull/388 by @CognitiveDisson.
  • WorkspaceSettings.autoCreateSchemes attribute https://github.com/tuist/xcodeproj/pull/399 by @pepibumur
  • Additional Swift 5 fixes: https://github.com/tuist/xcodeproj/pull/402 by @samisuteria
  • Make build phase name public by @llinardos.
  • Can access embed frameworks build phase for a target by @llinardos.
  • Added com.apple.product-type.framework.static to PBXProductType. https://github.com/tuist/xcodeproj/pull/347 by @ileitch.
  • Can add a not existing file to a group https://github.com/tuist/xcodeproj/pull/418 by @llinardos.
  • Support for Swift PM Packages https://github.com/tuist/xcodeproj/pull/439 https://github.com/tuist/xcodeproj/pull/444 by @pepibumur @yonaskolb.
  • LaunchAction.customLaunchCommand attribute https://github.com/tuist/xcodeproj/pull/451 by @pepibumur.
  • XCBuildConfiguration.append method https://github.com/tuist/xcodeproj/pull/450 by @pepibumur.


  • Carthage integration https://github.com/tuist/xcodeproj/pull/416 by @pepibumur.
  • Relative path is wrong when referencing file outside of project folder https://github.com/tuist/xcodeproj/issues/423 by @damirdavletov
  • [crash] Fatal error: Duplicate values for key https://github.com/tuist/xcodeproj/issues/426 by @toshi0383
  • Change PBXContainerItemProxy.remoteGlobalID attribute to support object references https://github.com/tuist/xcodeproj/pull/445 by @yonaskolb
  • Dead lock in the PBXObjects.delete method https://github.com/tuist/xcodeproj/pull/449 by @pepibumur


  • OSLogs https://github.com/tuist/xcodeproj/pull/453 by @pepibumur.

6.7.0 - 2019-03-31 12:49:42


  • Breaking Make PBXBuildPhase.files optional to match Xcode's behavior https://github.com/tuist/xcodeproj/pull/391 by @pepibumur.


  • Add location variable to XCWorkspaceDataElement https://github.com/tuist/xcodeproj/pull/387 by @pepibumur.

6.6.0 - 2019-03-01 03:29:27


  • Fix adding files to PBXBuildPhase https://github.com/tuist/xcodeproj/pull/380 @danilsmakotin.
  • Improve project encoding performance https://github.com/tuist/xcodeproj/pull/371 by @CognitiveDisson.
  • Project decoding performance issue https://github.com/tuist/xcodeproj/pull/365 by @CognitiveDisson.
  • Fix PBXTarget extension methods https://github.com/tuist/xcodeproj/pull/367 by @danilsmakotin.


  • Added GPUFrameCaptureMode and GPUValidationMode options to LaunchAction https://github.com/tuist/xcodeproj/pull/368 by @schiewe.
  • Add Swiftformat https://github.com/tuist/xcodeproj/pull/375 by @pepibumur.


  • Breaking Rename GPUFrameCaptureMode cases to start with a lowercase letter https://github.com/tuist/xcodeproj/pull/375 by @pepibumur.
  • Fix linting issues https://github.com/tuist/xcodeproj/pull/375 by @pepibumur.

6.5.0 - 2019-02-02 05:05:56


  • Make Xcode.Supported.xcschemeFormatVersion public https://github.com/tuist/xcodeproj/pull/361 by @yonaskolb.


  • Fix remote target dependency https://github.com/tuist/xcodeproj/pull/362 by @mxcl.

6.4.0 - 2019-01-06 11:34:06


  • Added projReferenceFormat to PBXOutputSettings to allow changing the output format of generated references. withPrefixAndSuffix will give the legacy behaviour xcode will generate 32 character references as XCode does. https://github.com/tuist/xcodeproj/pull/345 by @samskiter.
  • Danger https://github.com/tuist/xcodeproj/pull/357 by @pepibumur.
  • Support for WorkspaceSettings https://github.com/tuist/xcodeproj/pull/359 by @pepibumur.

6.3.0 - 2018-10-18 09:33:52


  • Added parallelizable and randomExecutionOrdering attributes to XCScheme.TestableReference https://github.com/tuist/xcodeproj/pull/340 by @alvarhansen.


  • Fixed possible generated UUID conflicts https://github.com/tuist/xcodeproj/pull/342 by @yonaskolb.
  • Fixed not working PBXFileElement.fullPath(sourceRoot:) method https://github.com/tuist/xcodeproj/pull/343 by @Vyeczorny.

6.2.0 - 2018-10-12 08:20:07


  • Carthage and CocoaPods support https://github.com/tuist/xcodeproj/pull/339 by @pepibumur.


  • Improved writing performance https://github.com/tuist/xcodeproj/pull/336 https://github.com/tuist/xcodeproj/pull/337 https://github.com/tuist/xcodeproj/pull/338 by @yonaskolb.
  • Replaced Swift Package Manager dependency with PathKit https://github.com/tuist/xcodeproj/pull/334 by @yonaskolb.

6.1.0 - 2018-10-10 08:41:43


  • Added ability to pass in a PBXObject into the PBXProject.targetAttributes dictionary, which will be encoded into its UUID. Can be used for TestTargetID https://github.com/tuist/xcodeproj/pull/333 by @yonaskolb.


  • Changed XCScheme.BuildableReference init to make blueprint a PBXObject and added a setBlueprint(:) function https://github.com/tuist/xcodeproj/pull/320 by @yonaskolb.
  • Bump AEXML version to 4.3.3 https://github.com/tuist/xcodeproj/pull/310 by @pepibumur.
  • Improves performance of object references https://github.com/tuist/xcodeproj/pull/332 by @yonaskolb.
  • Prefix reference with object type acronym. eg. PBXFileReference becomes FR_XXXXXXXXXXXXXXXXX https://github.com/tuist/xcodeproj/pull/332 by @yonaskolb.
  • Add TEMP prefix to temporary unfixed reference values https://github.com/tuist/xcodeproj/pull/332 by @yonaskolb.


  • Fixed written order of scheme attributes in Swift 4.2 https://github.com/tuist/xcodeproj/pull/325 and https://github.com/tuist/xcodeproj/pull/331 by @yonaskolb and @drekka

6.0.1 - 2018-09-24 15:38:29


  • Fixes PBXProject attributes not being set properly https://github.com/tuist/xcodeproj/pull/318 by @yonaskolb.
  • Fixed remoteGlobalID typo https://github.com/tuist/xcodeproj/pull/315 by @yonaskolb.
  • Fixed XCBuildConfiguration.buildConfiguration type https://github.com/tuist/xcodeproj/pull/316 by @yonaskolb.

4.3.1 - 2018-09-19 07:38:46


  • Compilation issue when compiling the project with Swift 4.2 and the release configuration https://github.com/tuist/xcodeproj/pull/309 by @keith

6.0.0 - 2018-09-18 08:14:47

Note: Migration guidelines are included in the project README.


  • Breaking Make PBXObjectReference internal https://github.com/tuist/xcodeproj/pull/300 by @pepibumur.
  • Breaking Make PBXObjects internal https://github.com/tuist/xcodeproj/pull/300 by @pepibumur.
  • Breaking Move PBXObjects helpers to PBXProj https://github.com/tuist/xcodeproj/pull/300 by @pepibumur.

5.2.0 - 2018-09-14 08:13:31


  • Some tweaks to support Xcode 10 https://github.com/tuist/xcodeproj/pull/298 by @pepibumur.