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.
Run the command –
sudo gem 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:
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.
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
Now type the command :
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
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.
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
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:
~> 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
' : Any version lower than 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 searches for the pod in the CocoaPod repository and installs it.
The pod is added to the
Podfile and Podfile.lock are two different files.
Besides that the
pod install line does two other things:
- CocoaPods creates a
.xcworkspacein 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.
Open your Xcode project through the file
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.
If it doesn’t import, clean your project using
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 => 'https://github.com/Alamofire/Alamofire.git'
pod 'Alamofire', :git => 'https://github.com/Alamofire/Alamofire.git', :branch => 'dev'
pod 'Alamofire', :git => 'https://github.com/Alamofire/Alamofire.git', :tag => '3.1.1'
pod 'Alamofire', :git => 'https://github.com/Alamofire/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.
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 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.
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
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.
That’s all for CocoaPods tutorial. You can think of it as Maven or Gradle dependency management plugins.