Using CocoaPods - codepath/ios_guides GitHub Wiki

Overview

This guide covers 1) setting-up CocoaPods, and 2) adding and installing Pods into your Xcode project. By the end of it you'll be ready for guides on actually using the Pods you need.

New project? Consider Swift Package Manager (SPM) first — it ships with Xcode (supported for iOS since Xcode 11), needs no external install, and is Apple's recommended dependency manager for new projects. The CocoaPods guide compares it with CocoaPods.

Necessary knowledge

Basic level in Xcode
Novice level in Terminal

One-time Setup

Install CocoaPods

Install CocoaPods by typing the following commands into Terminal

sudo gem install cocoapods    # Install CocoaPods gem

☝️ NOTE This matches the official CocoaPods install guide, which uses sudo together with the default macOS Ruby. If you would rather avoid sudo (recommended), install Ruby via a version manager such as rbenv or rvm, switch to that Ruby, and run gem install cocoapods without sudo. On Apple Silicon Macs you can also install via Homebrew with brew install cocoapods — Homebrew's prefix is /opt/homebrew on arm64, not /usr/local, so do not pass -n /usr/local/bin (an Intel-Mac path) to gem install.
Just close your Terminal window and re-open it to complete setup!

Note: Older versions of this guide ran pod setup after the gem install to clone the master specs repo. As of CocoaPods 1.8 the CDN trunk source is the default, so pod setup is no longer required and pod install will fetch only the specs it needs on demand.

Adding Cocoapods to your project

Step 1 - Set your Terminal's directory

First you need set your Terminal's Present Working Directory to the folder containing your XCode Project.

Type the characters "cd" + space
Drag the folder containing your .xcodeproject file to your terminal, then hit your return key

Watch the cd gif here

Step 2 - Add your Podfile

CocoaPods uses a text file named Podfile to define your project's Pods. To add your Podfile:

Type pod init into your terminal
Type open -a Xcode Podfile and edit your Podfile in Xcode

Watch the add your Podfile gif here

Step 3 - Add your Pods and install

First, you can delete everything in this file
Add use_frameworks!
Add a row for each Pod you're installing, then save

use_frameworks!

pod 'MBProgressHUD'
pod 'Alamofire', '~> 5.0'

Note: Your Pods will be different. These are two examples.

Next have CocoaPods install typing the following into terminal

pod install

Note: If pod install is taking more than 60 seconds, see FAQ

Watch the add Pods and install gif here

Step 4 - Open your new Workspace file

After your first pod install, CocoaPods will create a new .xcworkspace file for you, which includes has your CocoaPods as well. Only use your .xcworkspace from now on.

Close your .xcproject file
Open your new .xcworkspace file, which you can find in your project's folder

If you later need to change your Podfile to bring-in new Pods, simply run pod install again.

Step 5 - Importing your pod

In any Swift file where you want to use the library, you need to import it.

import UIKit
import MBProgressHUD

Step 6 - Done! Use your CocoaPods!

We're done! Now you can use your Pods– just follow the Pod maker's tutorials.

For example, now you can use your Pod in a ViewController.

class ViewController: UIViewController {
    var progressHUD : MBProgressHUD!
    ...
}

Note: Your Pods will be different. This is one example.

FAQ

My terminal froze during `pod install`! What do I do?

If pod install hangs for several minutes on Updating spec repo "master", the most likely cause is a leftover git-based master specs repo on disk from a CocoaPods < 1.8 install. Drop it and let the CDN trunk source take over:

Close your Terminal window, and open a new one
Type the following command

pod repo remove master

Now you can go back to step one and try again — pod install will fetch specs from the CDN on demand.

How do I know what to type in the Bridging Header or in the Podfile?

Answer: The Pod's developers will usually tell you what to write on their website.