How to Get Started With CocoaPods

In this tutorial, you’ll be learning about the CocoaPods dependency manager and how to implement it in your app. We’ll go through the steps from creating an Xcode project all the way to importing frameworks. Along the way, we will learn about some basic Terminal commands and what they do.

About CocoaPods

Before we get into actually implementing CocoaPods in our Xcode project, let’s talk a little bit about what it is and why you should use it in the first place.

What Is CocoaPods?

CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. It has over 35 thousand libraries and is used in over 2.4 million apps. CocoaPods can help you scale your projects elegantly. — CocoaPods website

CocoaPods is getting increasingly popular nowadays for Cocoa Touch development—and with good reason. CocoaPods is an easy-to-use, easy-to-implement dependency manager for your apps written in Swift or Objective-C.

What the Heck Is a Dependency Manager?

Glad you asked! In short, a dependency manager is a tool used to manage third-party frameworks. In CocoaPods, dependencies are listed in a text file called a podfile (which we will get to shortly) with simple one-line statements.

This solves the issue of having to download and add each framework manually to your Xcode project and then deleting and reinstalling outdated frameworks (that’s just a pain). Some libraries even use their own frameworks in their SDK (such as Firebase), and every time they make a small update, you have to manually reinstall everything!

Why Should I Use CocoaPods?

While there are other dependency managers out there (such as Carthage), CocoaPods is still the most widely used, and therefore, has the most libraries available for your use. Since it is the most popular, there are also more discussions regarding it on StackOverflow and other forums—that’s helpful in case you ever get stuck.

Let’s think of a common scenario: something that CocoaPods (or any dependency manager) can solve. You set out to build an app. This app is huge, and you don’t want to rewrite code that someone else has already written, so you create a list of libraries that you think would be good to have in your project. It would be nearly impossible to be able to correctly install all of them manually and future-proof your code at the same time! This is where CocoaPods comes in.

Using CocoaPods

CocoaPods is built with Ruby, which is installed by default on versions of macOS. In this tutorial, we will be using gem to install the necessary Ruby gems to get CocoaPods set up. Gems are Ruby packages, and since CocoaPods is a Ruby program, it needs to be installed with Ruby’s package manager.

To start, open up a new terminal window. You can find this in Applications > Utilities or you can simply search for it in Spotlight Search (Command-Space).

1. Installation

Enter the following line of code in your Terminal.

$ sudo gem install cocoapods

Then, press Enter. You will be prompted to enter your password, and when you have done so, press Enter again. After you do so, CocoaPods will install, and when it is finished your terminal should look something like this:

2. Create an Xcode Project

CocoaPods can be added to any existing Xcode project, but for the purposes of this tutorial, let’s create a new one. Please feel free to follow along with your own Xcode project and skip this step.

Launch Xcode

After launching Xcode, you will see three options. Click on the second option which says Create a new Xcode project. If you have used Xcode in the past, your recent projects will appear on the right.

Choose Your Application Type

For this project, we will choose a single view application, but you can choose any template you need to for your specific purposes.

Configure Your Project

Now, name your project and choose Swift as the language. Here, you can also set the bundle identifier and choose the devices that your app would support. Again, it is up to you, but I will name it CocoaPods.

3. Create a Podfile

After you have created an Xcode project, the next step is to navigate to it using the terminal. Many of you may be familiar with this, but let’s go over it together; after all, practice makes perfect!

Find the Project Directory

Before you can navigate to the project directory using the command line, it is a good idea to locate your project using the Finder first. In this case, my project is on my desktop in a folder named Tuts+.

Basic Commands

sudo—a way to override your user’s privileges and become a super-user of the computer. This is why it requires an admin password when using it. We used this command while installing CocoaPods earlier.
ls—lists all of the contents in the current directory. This command comes in handy if you don’t want to use the Finder to browse files; you can simply list them using this command in your Terminal.
cd —this command is used to change directories. If you write cd alone, you will move out of the current directory. After using ls (to see the directories), you can write the name of the directory you want to enter.
vim—this is one of my favorites. Remember the podfile that I mentioned earlier? You can edit this file using the default TextEdit, but I like to use the terminal. vim is a command line text editor which we will be using to edit our podfile.

Some bonus ones: These aren’t necessary right now, but hey, why not learn some more cool things while you’re at it?

mkdir —you can kind of tell what this one does by its name; it makes a directory (now that wasn’t so hard, was it?). You have to type the name of the directory after the keyword mkdir and voila, there you have a folder appear (almost) instantly.
help—this command is nice because (as the name suggests), it helps you out if you ever forget a command. Just type help into your Terminal window, and a list of basic commands will pop up with their meaning.

Initialize CocoaPods

Since you have already installed CocoaPods on your machine, the next thing to do is actually initialize your Xcode project. Find where your project is located on your hard drive and follow along in your own directory.

After you are done navigating to your project via the terminal, your window should look like this. I have highlighted my project name, and yours should appear in the same spot. It should look something like this:

Once you are in your project directory, you will need to initialize CocoaPods, resulting in a podfile being created. To do this, type the following line into your terminal window:

$ pod init

This will initialize CocoaPods in your project folder, and you will see a file called podfile show up.

4. Set Up the Libraries

Hurray! CocoaPods is now ready to manage your project’s dependencies. The next step is to actually add the desired libraries into your Xcode project—after all, that’s what we are here for.

Edit the Podfile

Remember vim, the text editor? We will be using it to add the desired frameworks to the app. Type the following line to edit your podfile:

$ vim podfile

To get into edit mode, you just type i, as in “insert.”

Add Pods to the Podfile

In CocoaPods, there are two ways to get the command for the framework you want. You can usually find the podfile line in the framework’s GitHub project description. If not, go to the CocoaPods website and search for the library there and their podfile lines.

Below, I have a line for Firebase.

pod 'Firebase/Core'

As I said, it doesn’t really matter where you get them from. Find one of these and follow the steps below. Now, enter your line under the comment which says:

# Pods for

That’s all that’s needed to add frameworks. See how easy that was? Now, we need to exit the vim editor and move on to the next step.

Exiting the `vim` Editor

In order to save your changes and exit the vim editor, you need to:

Press the Esc key to get out of edit mode.
Type :x (the save and exit command).
Press Enter.

Install CocoaPods

This step is another one-liner. All you need to do is, in your project directory, type the following command:

$ pod install

This will download any frameworks you listed in your podfile and install them to your Xcode project. The pods should be now available to import just as a regular framework would be (by using import at the top of your source file).

5. Conclusion

I hope this tutorial was helpful. We covered installing CocoaPods, basic terminal commands, and how to add pods to your podfile. CocoaPods is a fast, easy-to-use, and effective tool for managing your dependencies, and it is very commonly used.

And remember:

You’ll need to access your project only through .xcworkspace and not .xcodeproj.
The podfile can be edited using any text editor, and can also be edited within your Xcode.
Run pod install from the terminal after changing your podfile so the dependencies will be removed or added.

While you’re here, check out some of our other posts on coding iOS apps!