Using CocoaPods

<Adding Pods to an Xcode project

Before you begin

  1. Check the Specs repository or to make sure the libraries you would like to use are available.
  2. Install CocoaPods on your computer.


  • Create a Podfile, and add your dependencies:
pod 'AFNetworking', '~> 2.0'  
pod 'ObjectiveSugar', '~> 0.5'
  • Run $ pod install in your project directory.
  • Open App.xcworkspace and build.

<Creating a new Xcode project with CocoaPods

To create a new project with CocoaPods, follow these simple steps:

  • Create a new project in Xcode as you would normally.
  • Open a terminal window, and $ cd into your project directory.
  • Create a Podfile. This can be done by running $ touch Podfile.
  • Open your Podfile. The first line should specify the platform and version supported.
platform :ios, '6.0'
  • Add a CocoaPod by specifying pod '$PODNAME' on a single line
pod 'ObjectiveSugar'
  • Save your Podfile.
  • Run $ pod install
  • Open the MyApp.xcworkspace that was created. This should be the file you use everyday to create your app.

<Integration with an existing workspace

Integrating CocoaPods with an existing workspace requires one extra line in your Podfile. Simply specify the .xcworkspace root filename like so:

workspace 'MyWorkspace'

<Should I ignore the Pods directory in source control?

Whether or not you check in your Pods folder is up to you, as workflows vary from project to project. We recommend against adding the Pods directory to your .gitignore. However you should judge for yourself, here are the pros and cons:


  • Smaller repo under source control
  • CocoaPods given the availability of the sources is capable to recreate (almost) the same exact installation.
  • No conflicts to handle in the dependencies of the management system of source control.


  • The sources of the Pods can go down.
  • External sources are not recreated perfectly (at the moment the commit is not used) and in some cases will never be (zip files)
  • Requires internet connection and the installation of CocoaPods for clients of the project.

<What is a Podfile.lock

This file keeps track of what version of a Pod is installed. For example the following dependency might install RestKit 0.10.3:

pod 'RestKit'

Thanks to the Podfile.lock every machine which runs pod install on the hypothetical project will use RestKit 0.10.3 even if a newer version is available. CocoaPods will honour this version unless the dependency is updated on the Podfile or pod update is called. In this way CocoaPods avoids headaches caused by unexpected changes to dependencies.

This file should always be kept under version control.

<What is happening behind the scenes?

In Xcode, with references directly from the ruby source, it:

  1. Creates or updates a workspace.
  2. Adds your project to the workspace if needed.
  3. Adds the CocoaPods static library project to the workspace if needed.
  4. Adds libPods.a to: targets => build phases => link with libraries.
  5. Adds the CocoaPods Xcode configuration file to your app’s project.
  6. Changes your app's target configurations to be based on CocoaPods's.
  7. Adds a build phase to copy resources from any pods you installed to your app bundle. i.e. a ‘Script build phase’ after all other build phases with the following:
    • Shell: /bin/sh
    • Script: ${SRCROOT}/Pods/

Note that steps 3 onwards are skipped if the CocoaPods static library is already in your project. This is largely based on Jonah Williams' work on Static Libraries.

<Pods and Submodules

CocoaPods and git submodules attempt to solve very similar problems. Both strive to simplify the process of including 3rd party code in your project. Submodules link to a specific commit of that project, while a CocoaPod is tied to a versioned developer release.

<Switching from submodules to CocoaPods

Before you decide to make the full switch to CocoaPods, make sure that the libraries you are currently using are all available. It is also a good idea to record the versions of the libraries you are currently using, so that you can setup CocoaPods to use the same ones. It's also a good idea to do this incrementally, going dependency by dependency instead of one big move.

  1. Install CocoaPods, if you have not done so already
  2. Create your Podfile
  3. Remove the submodule reference
  4. Add a reference to the removed library in your Podfile
  5. Run pod install