CocoaPods Swift XCode Tutorial

Filed Under: iOS

As a beginner or seasoned iOS Developer, at some point in time, you must have come across CocoaPods. It’s one of the most important concepts to master in iOS Developer and in this tutorial we’ll be doing just the same.


CocoaPods are dependency manager for your XCode projects.

Dependency Managers are responsible for managing libraries and frameworks added to your project. Instead of you downloading the libraries manually and adding it to the project, they do it for you.

CocoaPods itself is a library that’s written in Ruby. It holds a central repository of all the third party libraries.

You can always search in the repository for the third party pod name and version.

What is a Pod?

A Pod is a single library or framework that’s added to our project.

So where are these libraries installed and stored for the XCode Project?

There’s a file Podfile in which we store our Pods and their versions.

Let’s first install CocoaPods on our mac through the terminal.

Install CocoaPods

Run the command – sudo gem install cocoapods
install cocoapods

CocoaPods is installed on our system! You can run the same command to update your CocoaPods to latest stable version.

To get a list of the cocoapods plugins, run the command: gem list --local | grep cocoapods.

You should see something like this on your terminal:

cocoapods pod list

Now let’s create a new XCode project and install a third-party library in it using CocoaPods!

Creating XCode Project

Launch XCode and start a new Project. iOS Project | Single View Application.

XCode create new project for CocoaPods

Installing Your First Pod

To install your first library using CocoaPods you need to close XCode first. Launch terminal and cd into the XCode Project directory.

For me the Xcode Project location is at cd Desktop/workspace/CocoaPodsTest.

Now type the command : pod init.

This initializes the dependency manager for our project and creates the Podfile.

Now you can open the Podfile and add the libraries in it. You can use Xcode/Vim editor to edit the files.

It’s recommended NOT to use a text editor since they can corrupt the formatting.

To use the vim editor do a vim Podfile.

To use XCode for editting run:

open -a Xcode Podfile

We’re using vim editor here to update our pod file.

Let’s see how the newly created Podfile looks like.

cocoapods pod file

Uncomment the platform line. You can set whatever platform you like. Here we’re using ios. Set the ios version to 11.3 or whatever is the latest version when you do this.

platform :ios, '11.3'

use_frameworks! line is mandatory for Swift libraries.

We can set different pods inside different targets. Targets are like different builds (Builds for iPhone, iPad etc or debug release targets).

We’re using this open source library as our pod.

Add the following pod statement just after the use_frameworks! line:

pod 'Macaw', '~> 0.9.1'

We set the library name followed by a comma and an optional version name.

To set only a certain version you can do: pod 'Macaw', '0.9.1'.

To set the latest version just do: pod 'Macaw'

~> is an optimistic operator.

  • '~> 0.9.1' means versions from 0.9.1 to 0.10. Excluding version 0.10 and higher.
  • '~> 0.1' means versions from 0.1 to 1. Excluding 1 and higher
  • '~> 0' means version 0 and higher. This is equivalent to having any version number. You need not set this. The Podfile automatically finds this for you.
  • '> 0.1': Any version higher than 0.1
  • '>= 0.1' : Version 0.1 and any higher version
  • '< 0.1' : Any version lower than 0.1
  • '<= 0.1' : Version 0.1 and any lower version

Now do a :wq in the vim editor to save and exit to the terminal.

In your terminal now install the pod using:

pod install

pod install searches for the pod in the CocoaPod repository and installs it.

The pod is added to the Podfile.lock file.

Podfile and Podfile.lock are two different files.

Besides that the pod install line does two other things:

  • CocoaPods creates a .xcworkspace in our XCode project. It contains the library dependencies.
  • It creates a Podfile.lock file
  • Moving ahead we'll be opening our XCode project from this file. CocoaPods added some scripts in the build phases of our target.

    swift cocoapods build settings

Open your Xcode project through the file .xcworkspace.

You can do this using : open CocoaPodsTest.xcworkspace/ on the terminal.

CocoaPodsTest is the XCode project name I've set. Replace it with the name of your XCode project.

Now add the library to your project via the import statement. import Macaw in this case and you're ready to use the library in your XCode project.

swift cocoapods pod imported

If it doesn't import, clean your project using Command+Shift+K

In your Podfile you can add pods by specifying the local path if you have it on your system or the git url too. With git you can use a specific tag/commit/branch also.

pod 'MyLibrary', :path => '~/workspace/MyLibrary'
pod 'Alamofire', :git => ''
pod 'Alamofire', :git => '', :branch => 'dev'
pod 'Alamofire', :git => '', :tag => '3.1.1'
pod 'Alamofire', :git => '', :commit => '0f506b1c45'

Deleting CocoaPods from your project

Run the following set of commands if you want to delete CocoaPods from the XCode Project.

pod deintegrate
pod clean
rm Podfile

Remove Library from CocoaPod

To remove a library from your CocoaPod, remove the pod line from the Podfile and do a pod install again or do a pod update.

pod install and pod update aren't the same. Let's see how they differ from each other.

pod install vs pod update

pod install is used when new pods are added in the Podfile. It installs them but doesn't install the older pods again irrespective of whether there is a new version for them. The older pods would be fetched from the Podfile.lock directly.

pod update is used to update the pods already present in the Podfile.lock. pod update [PODNAME] is used to update only the pod that is mentioned.

pod install does not update already installed pods even if a new version is available for them.

Running pod outdated would list all the pods that have a newer version available.

Importance of Podfile.lock

Once a pod is installed it is available inside Podfile.lock file.

When working on team projects, always commit the Podfile.lock. This way when a new user joins your team and clones the repository, pod install WON'T install the latest versions of the pods specified by operators.

Instead, the pods would be installed from the Podfile.lock directly thus keeping it exactly the same for all.

Though if he/she later does a pod update, CocoaPods would update his pods to the latest versions.

swift cocoapods add another pod

That's all for CocoaPods tutorial. You can think of it as Maven or Gradle dependency management plugins.

Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors