Create and modify Xcode projects from Ruby.
Latest commit 48d7e22 Feb 11, 2017 @DanToml DanToml committed on GitHub Merge pull request #466 from CocoaPods/ks/system-framework-return
Change return value of adding system framework


Build Status Coverage Code Climate

Xcodeproj lets you create and modify Xcode projects from Ruby. Script boring management tasks or build Xcode-friendly libraries. Also includes support for Xcode workspaces (.xcworkspace), configuration files (.xcconfig) and Xcode Scheme files (.xcscheme).

It is used in CocoaPods to create a a collection of supplemental libraries or frameworks, for all platforms Xcode supports.

The API reference can be found here.

Installing Xcodeproj

Xcodeproj itself installs through RubyGems, the Ruby package manager. Install it by performing the following command:

$ [sudo] gem install xcodeproj


To begin editing an xcodeproj file start by opening it as an Xcodeproj with:

require 'xcodeproj'
project_path = '/your_path/your_project.xcodeproj'
project =

Some Small Examples To Get You Started

Look through all targets

project.targets.each do |target|

Get all source files for a target

target = project.targets.first
files = do |pbx_build_file|
    pbx_build_file.file_ref.real_path.to_s do |path|
  path.end_with?(".m", ".mm", ".swift") do |path|

Set a specific build configuration to all targets

project.targets.each do |target|
  target.build_configurations.each do |config|
    config.build_settings['MY_CUSTOM_FLAG'] ||= 'TRUE'

Command Line Tool

Installing the Xcodeproj gem will also install a command-line tool xcodeproj which you can use to generate project diffs, target diffs, output all configurations and show a YAML representation.

For more information consult xcodeproj --help.


All Xcodeproj development happens on GitHub. Contributing patches is really easy and gratifying.

Follow @CocoaPods to get up to date information about what's going on in the CocoaPods world.


These works are available under the MIT license. See the LICENSE file for more info.