CocoaPods Tutorial for Swift: Getting Started

Use this CocoaPods Tutorial for Swift to learn how to install and manage third-party library dependencies in your Swift projects. By Rony Rozen.

4.8 (43) · 1 Review

Download materials
Save for later
Update note: Rony Rozen updated this tutorial for Xcode 11 and Swift 5. Joshua Greene wrote the original.

CocoaPods is a popular dependency manager for Swift and Objective-C Cocoa projects. Thousands of libraries and millions of apps use it, according to the CocoaPods website. But what is a dependency manager and why do you need one?

A dependency manager makes it easy to add, remove, update and manage the third-party dependencies your app uses.

For example, instead of reinventing your own networking library, you can easily pull in Alamofire using a dependency manager. You can specify either the exact version to use or a range of acceptable versions.

This means that even if Alamofire gets an update with changes that aren’t backward-compatible, your app can continue using the older version until you’re ready to update it.

In this tutorial, you’ll learn how to use CocoaPods with Swift. Specifically, you’ll:

  • Install CocoaPods.
  • Work with a functional demo app that gets you thinking about ice cream.
  • Use CocoaPods to add networking.
  • Learn about semantic versioning.
  • Add another library using a flexible version.

This tutorial also includes classes that use Core Graphics. While knowledge of Core Graphics is beneficial, it’s not required. If you’d like to learn more, read our Modern Core Graphics With Swift series.

Note: This CocoaPods tutorial requires basic familiarity with iOS and Swift development. If you’re completely new to iOS and/or Swift, then please check out some of the other written and/or video tutorials on this site before doing this tutorial. Or, dive into our book, iOS Apprentice.

This tutorial also includes classes that use Core Graphics. While knowledge of Core Graphics is beneficial, it’s not required. If you’d like to learn more, read our Modern Core Graphics With Swift series.

Getting Started

Download the starter project by clicking the Download Materials button at the top or bottom of the tutorial.

Throughout this tutorial, you’ll work with an app called Ice Cream Shop, Inc. You’ll use CocoaPods to add dependencies to the app the easy way, instead of writing your own.

Before you can proceed with this tutorial, you need to install CocoaPods. Fortunately, CocoaPods uses Ruby, which ships with all versions of macOS X since version 10.7.

Open Terminal and enter the following command:

sudo gem install cocoapods

Enter your password when requested. The Terminal output will show various fetching, installing and documentation-related outputs, concluding with “XX gems installed”.

Note: You must use sudo to install CocoaPods, but once it’s installed, you won’t need to use it again in this tutorial.

Finally, enter this command in Terminal to complete the setup:

pod setup --verbose

This process takes a few minutes because it clones the CocoaPods Master Specs repository into ~/.cocoapods/ on your computer.

The verbose option logs progress as the process runs, allowing you to watch the process instead of seeing a seemingly “frozen” screen.

Awesome, you’re now set up to use CocoaPods!

Ice Cream Shop, Inc.

Your top client is Ice Cream Shop, Inc. Their ice cream is so popular they can’t keep up with customer orders at the counter. They’ve recruited you to create a sleek iOS app that allows customers to order ice cream right from their iPhones.

You’ve started developing the app and it’s coming along well. Take a look at your progress by opening IceCreamShop.xcodeproj, then building and running. You’ll see a mouth-watering vanilla ice cream cone:

Ice Cream Shop, Inc.'s start page

The user should be able to choose an ice cream flavor from this screen, but that’s not possible yet. Your first step is to finish implementing this functionality.

Open Main.storyboard from the Views/Storyboards & Nibs group to see the app’s layout. Here’s a quick overview of the heart of the app, the Choose Your Flavor scene:

Components of the Choose Your Flavor scene

  • PickFlavorViewController is the view controller for this scene. It handles user interaction and provides the data for the collection view that displays the different ice cream flavors.
  • IceCreamView is a custom view that displays an ice cream cone based on the backing mode, Flavor.
  • ScoopCell is a custom collection view cell that contains a ScoopView, which gets colors from a Flavor model.

While every Ice Cream Shop, Inc. location has signature flavors in common, each carries its own local flavors, too. For this reason, a web service needs to provide the data for the Flavors.

However, this still doesn’t explain why users can’t select their ice cream flavors.

Open PickFlavorViewController.swift, found under the Controllers group, and you’ll see a stubbed method:

private func loadFlavors() {
  // TO-DO: Implement this

Aha, there are no flavors! You need to implement the function!

While you could use URLSession and write your own networking classes, there’s an easier way: Use Alamofire!

You might be tempted to download this library and drag the source files right into your project. However, that’d be doing it the hard way. CocoaPods provides a much more elegant and nimble solution.

Installing Your First Dependency

Your first step is to close Xcode. Yeah, you read that right.

It’s time to create the Podfile, where you’ll define your project’s dependencies.

Open Terminal and navigate to the directory that contains your IceCreamShop project by using the cd command:

cd ~/Path/To/Folder/Containing/IceCreamShop

Next, enter the following command:

pod init

This creates a Podfile for your project.

Finally, type the following command to open the Podfile using Xcode for editing:

open -a Xcode Podfile
Note: Don’t use TextEdit to edit the Podfile because it replaces standard quotes with more graphically-appealing typeset quotes. This can cause CocoaPods to become confused and throw errors. Instead, use Xcode or another programming text editor to edit your Podfile.

The default Podfile looks like this:

# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'

target 'IceCreamShop' do
  # Comment the next line if you're not using Swift and don't want to use dynamic frameworks

  # Pods for IceCreamShop


Delete the # and space before platform, then delete the other lines starting with #.

Your Podfile should now look like this:

platform :ios, '9.0'

target 'IceCreamShop' do


This tells CocoaPods your project targets iOS 9.0 and will use frameworks instead of static libraries. While Swift and CocoaPods both support static linking, not all libraries you include do. One of them that you’ll use in this project does not.

If you’ve only programmed in Swift, this may look a bit strange. That’s because the Podfile is actually written in Ruby. You don’t need to know Ruby to use CocoaPods, but you should be aware that even minor text errors will cause CocoaPods to throw errors.