The open-source community for iOS is amazing. There are so many high-quality, incredibly useful open-source projects out there now that it would be crazy to work on an iOS project without bringing in at least a few open-source projects. However, manually managing each of the libraries that you bring in can be tedious at best. Most of them are hosted on GitHub, which has improved a lot in the last few years to streamline the process. With GitHub for Mac, it’s easy to quickly clone a project straight from your browser, but you still have to move the appropriate files into your Xcode project. And then you have to do it all again when the project is updated and you want to take advantage of the latest release.

It doesn’t have to be this way.

CocoaPods

CocoaPods is the best way to manage library dependencies with Xcode. It’s still in the alpha phase, but it’s continually being improved. With CocoaPods, you can easily manage your project dependencies, even specifying the specific version number for each. This is all tracked in a plaintext file, so you can keep this in your source repository and your whole team will automatically be in sync. As an added bonus, you won’t have to keep the projects in your source repository, so you can keep your repository’s footprint small.

Installation

CocoaPods is distributed as a Ruby gem. If you’re new to Ruby, you should consider using an environment manager like rbenv to keep track of your Ruby environments. It’s not just for Rails—more and more command line tools are being written in Ruby, and they often have specific Ruby version requirements. I wrote a simple guide to getting started with rbenv that will have you up and running in no time.

If you don’t have it already, install Ruby 2.0.0-p247. CocoaPods will work in older versions, but I wouldn’t go older than 1.9.3. It’s distributed as a gem, so installing is simple.

Terminal 1 gem install cocoapods

This will download and install CocoaPods and its dependencies. (Don’t forget to rehash if you’re using rbenv.)

Now, perform the initial setup, which will create ~/.cocoapods, setup the initial podspec repos, and more.

Terminal 1 pod setup

Installation is that simple. You’re ready to get started.

Podfile

Dependencies are tracked in a special plaintext file named Podfile. You should create this file in the same directory as your Xcode project. The first line of this file tells CocoaPods what platform your project is targeting (iOS or OS X), and the subsequent lines list the dependencies for your project.

E.g., a very simple iOS Podfile specifying the latest LastFm and TestFlightSDK frameworks:

Podfile 1 2 3 platform :ios pod 'LastFm' pod 'TestFlightSDK'

Note that the platform is case sensitive. If you want to specify the version for a pod, simply append the version number like so:

Podfile 1 2 3 platform :ios pod 'LastFm' pod 'TestFlightSDK', '1.2.6'

You can also prefix the version number with a version constraint to indicate a range of versions.

Podfile 1 2 3 platform :ios pod 'LastFm' pod 'TestFlightSDK', '~> 1.2'

Finding the pods you need for your project is simple thanks to the search function on the CocoaPods site.

Workspace Generation

Once your Podfile has been defined, the next step is to install the pods and generate the Xcode workspace. This, too, is quite simple. In the same directory as your Podfile, run the following command.

Terminal 1 pod install

This will download the pods and build a Xcode workspace that includes a Pods target in addition to your Xcode project. Note that you need to use the .xcworkspace file generated by CocoaPods from now on when working with your project.

Terminal 1 open YourProject.xcworkspace

Whenever you add a new pod to your Podfile, just run pod install again to regenerate the workspace.

Source Control

I like to keep the pods out of my source code repositories. You can update the ignore file for your source control repository to exclude the Pods/ directory created by CocoaPods.

.gitignore or .hgignore 1 Pods/

I like to keep the Podfile and Podfile.lock files in source control so that it’s easy to recreate the workspace using pod install after cloning the repository.

More Info

This is just the beginning of what CocoaPods can do. Explore more of the advanced features—such as specifying pods for certain targets—in the CocoaPods documentation.