CocoaPods is a dependency management system for iOS (and other Cocoa-based) projects. It is very similar in function and usage to npm for JavaScript and Bundler for Ruby.

Installing CocoaPods

CocoaPods is packaged as a Ruby gem. Since Ruby comes with new OS X installations, you can install CocoaPods simply by running the following commands in a terminal:

Non-M1 Macbook Installation

# Install Xcode Component Tools
xcode-select --install
# Install CocoaPods gem
sudo gem install cocoapods

M1 Macbook Installation

Step 1: Install Brew

# Update your xcode dev tools and wait for installation
xcode-select --install

# Install Brew (package manager)
/bin/bash -c "$(curl -fsSL"

# Add 'brew' as a terminal command (change {USER_NAME})
echo 'eval $(/opt/homebrew/bin/brew shellenv)' >> /Users/{USER_NAME}/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Verify Installation
which brew

Step 2: Install cocoapods using Brew

brew install cocoapods

# Verify the installation from brew and get the Version number:
brew info cocoapods
# ^example output: cocoapods: stable 1.10.1 (bottled)

# Go to your project directory
cd path/to/project

# Install pods (REMEMBER to run this in your project folder)
sudo arch -x86_64 gem install ffi
arch -x86_64 pod init
arch -x86_64 pod install
⚠️ NOTE Get the {VERSION} from the brew info cocoapods command

Note: There are alternate instructions if you need to perform a sudo-less install or install a beta version of CocoaPods.

Adding a Pod

You can find available Pods using the search box on the official CocoaPods site or using the Wantedly search. When you find a pod you want to add to your project, follow these steps:

Create the Podfile

You only need a single Podfile per project. The Podfile is a plain text file where you can add multiple pods.

  • From a terminal in the root directory of your project, run...

    pod init

⚠️ Common Issues

Please refer to these steps if you encounter issues when installing cocoapods.

On your terminal

Install ffi

If you get an error saying something like this: "need to install using arch" try this sudo arch -x86_64 gem install ffi

Re-installing dependency

If "pod install" doen't work, try this arch -x86_64 pod install

If you are having issues installing Ruby, gems, or cocoapods, try these:

Install RVM

Install Brew

Check out this stackoverflow in case you encounter even more issues.

Add dependencies to the Podfile

  • In the example below, we'll add Alamofire and a few others:

    # Uncomment the next line to define a global platform for your project
    # platform :ios, '9.0'
    # NOTE: Change the string below to the name of your project
    target 'YOUR_APP_NAME' do
      # Comment the next line if you're not using Swift and don't want to use dynamic frameworks
      # Pods for MyApp
      # This pulls in the latest version of Alamofire. IF you have an older version of Xcode, please use version 4.0 or check their documentation!
      pod 'AlamofireImage'
  • Refer to the podfile documentation to see versioning options and more complex use cases.

Download and integrate the dependencies into your project

  • From a terminal in the root directory of your project, run...

    pod install --verbose
  • CocoaPods currently forks the spec repo. If the pod install fails, you may need to update your current specs:

    pod repo update

Open the Xcode workspace

  • Close the project (MyApp.xcodeproject) if you have it open and open the workspace (MyApp.xcworkspace).
  • CocoaPods creates an additional project for all the dependencies so you need to open the .xcworkspace from now on (which will contain your original project and the pods project).:

    <Workspace version = "1.0">
    <FileRef location = "group:ParseLab.xcodeproj"></FileRef>
    <FileRef location = "group:Pods/Pods.xcodeproj"></FileRef>

Swift Support

CocoaPods version 0.36 was the first version to add support for Swift with the use_frameworks! directive.

As long as your app targets iOS8+, you can enable Swift support by adding the use_frameworks! directive to your Podfile:

platform :ios, '8.0'
use_frameworks!    # Instruct CocoaPods to use dynamic frameworks instead of static libraries for Pods

Consuming Swift Libraries

With the use_frameworks! directive, you can now consume Swift libraries using CocoaPods! After you've added use_frameworks! to your Podfile, you can directly import Swift libraries from your Swift code using the framework name (i.e. import AFNetworking).

Consuming Objective-C Libraries from Swift

With the use_frameworks! directive, you can also consume Objective-C libraries from your Swift code without the need of a bridging header anymore. You'll be able to directly import the framework (i.e. import AFNetworking).

Potential Issue: Unfortunately, all Objective-C Pods haven't been updated to work with the new dynamic frameworks behavior. You might come across certain Objective-C Pods that no longer build after adding the use_frameworks! directive. In these cases you can either not use the use_frameworks! directive (you'll now need to create a bridging header) or manually edit the offending Pod to help it find the headers (as done in the linked issue).

Removing CocoaPods

If you want to fully remove all traces of CocoaPods from your Xcode project, there's a tool that can do this for you. Run the following command to install the tool:

sudo gem install cocoapods-deintegrate

And then navigate to the directory that contains your project (the same directory that has the .xcodeproj and Podfile files) and run the following command:

pod deintegrate

Note: This will remove all traces of CocoaPods from your project, but will leave 3 files hanging around on disk. If you want to fully remove all traces of CocoaPods, you'll also want to delete the following 3 files: Podfile, Podfile.lock, and *.xcworkspace.

Alternatives to CocoaPods

Carthage is an alternative dependency management system for Cocoa applications that has gained some traction recently. It prides itself on being a simple dependency manager that avoids the complexity of CocoaPods. To keep this simplicity, it doesn't automatically integrate the dependencies into your project (you must do that yourself). It also only supports iOS8 and above.


Fork me on GitHub