Library / SDK
tuist/XcodeProj avatar
tuist/XcodeProj

XcodeProj's install snippet pins 8.12.0 while the library is on 9.17

Project brief: Read, update and write your Xcode projects. XcodeProj XcodeProj is a library written in Swift for parsing and working with Xcode projects.

2,226 stars356 forksSwiftMIT

At a glance

What is it?
tuist/XcodeProj is an MIT licensed Swift library for reading and writing Xcode project files, and it now handles both the property list format and the JSON format Xcode 27.2 introduced. The code is mature and the references are thorough. The copy and paste snippets in the file are two major versions behind the library they install.
Who is it for?
This fits anyone who needs to generate or edit an Xcode project from code, and the choice between it and writing a spec into a generator comes down to whether you want an object graph you can mutate in place or a declarative file you regenerate. Check four things.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly Swift, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • tuist/XcodeProj2,226 ★ · +10
Star history
Repository2026-07-312026-11-15
tuist/XcodeProj2.2k2.2k

10 Stars in the last 107 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Three version references in one file, and two of them are two majors behind

The installation section tells you to add the dependency in your package manifest, and the snippet it shows constrains the version:

swift
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"]),
        ]
)

The published releases visible are 9.17.5, 9.17.4, and 9.17.3, so the constraint names a release two major versions back. A reader who copies the snippet verbatim gets the eight series rather than the one the library is on, and nothing in the snippet says so. The scripting example further down names a third version, as an import comment suggesting an eight series requirement near the lower end of that line. So a single file offers two stale pins and a live one, which is the sort of thing that survives because nobody re-reads the examples after cutting a release.

The JSON format is experimental and says exactly how far it has been checked

The new capability is a JSON project format. A recent Xcode release can store a project as JSON rather than as a property list, and XcodeProj reads and writes both through the same object graph, so existing code keeps working. Writing preserves whichever format the project was read in, and converting is a single extra argument. What makes this section worth reading is the warning attached to it, because it is unusually specific about its own limits. It says the support is experimental, that the Xcode release in question is the first to write the format, that the mapping has only been verified against Apple's own library and hand written projects, that the details are expected to move, and that a converted project should be checked before it is committed. Three separate verification sources are named and one is explicitly absent: nothing has been round-tripped against a project Xcode itself produced.

Two Swift version pins and two ways to build the same repository

The root of the repository carries more toolchain configuration than source-adjacent files usually do. There is a version manager configuration in both a directory and a standalone file, a Swift version file, a formatter configuration, a linter configuration, a registry manifest for a package index, a dependency update configuration, and a changelog generator configuration alongside the changelog it produces. The two Swift version pins are the interesting pair, because a version file and a version manager entry can disagree and nothing in the file says which one the project actually builds against. There are also two ways to open the project. The contributing section says to clone and open the package manifest in Xcode, and the repository root contains both that manifest and a separate manifest for a different project generation tool, which is the tool maintained by the same organisation. So a contributor has an Xcode path and a generator path, and the guide only describes the first.

The contributing guide is two steps and neither of them runs the tests

The contributing section is two numbered items. Clone the repository over SSH, and open the package manifest in Xcode. That is the whole instruction set. There is no build command, no test command, no formatter invocation, and no linter invocation, in a repository that has a tests directory, a fixtures directory whose contents are expected outputs, a scripts directory, a formatter configuration, and a linter configuration. For a library whose entire job is to round-trip a proprietary text format, a fixtures directory is where the interesting test cases live, and the guide does not say how to run them or how to add one. The gap is not unusual for a project with a large outside contributor base driven through pull requests, but for anyone reporting a parsing bug it is the first thing in the file you will miss.

The stated inspiration is a Ruby library with the same name

The opening paragraph says the library is heavily inspired by two projects, one being the CocoaPods library of the same name and the other a JavaScript package of the same name from a package registry. The reference list reinforces the lineage rather than the ownership: seven links, of which one is a page describing the project file format, one is a parser explorer written years earlier, one is a blog post about identifier semantics, one is a Ruby port of a parser, one is the CocoaPods library, one is the parser the CocoaPods library itself uses, and one is a package summary for a build system's implementation. So the ancestry is: a Ruby gem, the parser under that gem, an older parser explorer, a JavaScript implementation, and a large build system's internal version. That history is genuinely useful to read, and it is also the clearest warning in the file that the format has no vendor specification behind it.

The user list is nine projects and it is maintained by pull request

There is a table of projects built on this library, and it is short enough to read in one pass: a linter for projects, a build rules implementation, an archiving tool, a code generation tool, the project generation tool maintained by the same organisation, another project generator, a Swift package manager front end, a privacy manifest generator, and a command line tool for projects. One of the nine is hosted on a different forge rather than the same one, which is a small sign of how the tool spread. The table also carries an invitation: if you are using the library in your project, open a pull request to add it. So the list is not a curated endorsement but a self-declared registry maintained by the same pull request flow as the code, with no criteria stated for inclusion and no indication of how old the entries are.

Identifier semantics are documented by a blog post

The single most load-bearing detail in a project file is that every object carries a twenty-four character hexadecimal identifier, and that a human reading the text cannot tell what any of them refer to. The reference list offers two things on that: a page describing the project file format at a personal site, and a blog post titled for identifier semantics. Neither is vendor documentation, because there is no vendor documentation, and one of the two is a decade-old personal page. The newer of the two is a blog. That is an honest thing for the project to point at, since the format is undocumented by Apple and every implementation has reverse engineered it separately, but it does mean the identifier rules this library depends on are defined by a third party's prose rather than by a specification anyone can be held to.

Editorial conclusion

This fits anyone who needs to generate or edit an Xcode project from code, and the choice between it and writing a spec into a generator comes down to whether you want an object graph you can mutate in place or a declarative file you regenerate. Check four things. Which version you pin, because the package snippet in the file names an eight series release while the published library is on a nine series line, and the scripting example names a different eight series version again. Whether you rely on the JSON format, because it is marked experimental, verified only against Apple's own library and hand written projects, with an explicit instruction to check a converted project before committing it. Where your identifiers come from, because the format is private and the reference offered for identifier semantics is a blog post rather than vendor documentation. And how you run the suite, since the contributing guide is a clone and an open, with no test step.

Frequently asked questions

How do I add XcodeProj to a Swift project?

Add the package URL to your package manifest with an up-to-next-major version constraint, and list XcodeProj as a target dependency. The snippet in the readme shows a constraint of 8.12.0 while the published releases are in the 9.17 line, so check the version before copying it.

Can XcodeProj read the JSON project format?

Yes, experimentally. A recent Xcode release can store a project as JSON rather than a property list, and XcodeProj reads and writes both through the same object graph. Writing preserves the format it was read in, and conversion takes one argument. The readme advises checking a converted project before committing it.

What projects use XcodeProj?

Nine are listed, including two project generators, a code generator, an archiving tool, a linter, a build rules implementation, a package manager front end, a privacy manifest generator, and a command line project tool. The list is kept by pull request and does not state criteria for inclusion.

How do I run the XcodeProj test suite?

The contributing guide does not say. It gives two steps, cloning the repository and opening the package manifest in Xcode, with no build, test, format, or lint command. The repository does contain tests, fixtures, scripts, and formatter and linter configurations.

What licence is XcodeProj released under?

MIT, with the licence file linked from the readme at the repository's main branch. The library is written in Swift and reads and writes both the property list project format and the newer JSON project format.

Official sources

  1. Official README
  2. Project repository
  3. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tuist-xcodeproj.svg)](https://hysenlabs.com/projects/tuist-xcodeproj)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tuist-xcodeproj.svg)](https://hysenlabs.com/projects/tuist-xcodeproj)

Was this useful?