Getting Started with CocoaPods

Jul 18, 2022#ios#xcode

CocoaPods is a popular dependency manager for Swift and Objective-C projects, will resolve dependencies between libraries, fetch the resulting source code, then link it together in an Xcode workspace to build your project.

CocoaPods uses a centralized Podspecs repository has over 91 thousand libraries and is used in over 3 million apps.

CocoaPods supports almost every way you would want to get source code; git, svn, bzr, http and hg. You can use your own private code repository to manage your own dependencies. It only requires a git repo, no server necessary.

Getting Started

  1. Install CocoaPods on your computer. CocoaPods is built with Ruby and it will be installable with the default Ruby available on macOS.
# Might require you to use sudo when installing
$ sudo gem install cocoapods

# To update CocoaPods you simply install the gem again
$ [sudo] gem install cocoapods

# Or for a pre-release version
$ [sudo] gem install cocoapods --pre
  1. Create a Podfile, and add your dependencies.
  2. Run pod install in your project directory.
  3. Open AppName.xcworkspace and build.

Note that CocoaPods itself does not require the use of a workspace. If you prefer to use sub-projects, you can do so by running pod install --no-integrate, which will leave integration into your project up to you as you see fit.

Whether or not you check in the Pods directory, the Podfile and Podfile.lock should always be kept under version control.


The Podfile is a specification that describes the dependencies of the targets of one or more Xcode projects. An example of a more complex Podfile can be:

platform :ios, '9.0'

target 'MyApp' do
  pod 'ObjectiveSugar', '~> 0.5'
  pod 'SSZipArchive'
  pod 'Objection', '0.9'

  target 'MyAppTests' do
    inherit! :search_paths
    pod 'OCMock', '~> 2.0.1'

post_install do |installer|
  installer.pods_project.targets.each do |target|
    puts "#{}"

Specifying pod versions using logical operators or optimistic operator ~> regarding semantic versioning.

  • Omit the version requirements to use the latest version of a Pod
  • Specify exact version number to freeze to a specific version of a Pod
  • > 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
  • ~> 0.1.2: Version 0.1.2 and the versions up to 0.2, not including 0.2 and higher
  • ~> 0.1: Version 0.1 and the versions up to 1.0, not including 1.0 and higher
  • ~> 0: Version 0 and the versions up to 1.0, not including 1.0 and higher


This file is generated after the first run of pod install, and tracks the version of each Pod that was installed.

CocoaPods will honour the Pod version in Podfile.lock unless the dependency is updated in the Podfile or pod update is called (which will cause a new Podfile.lock to be generated). In this way CocoaPods avoids headaches caused by unexpected changes to dependencies.


Whether or not you check in your Pods folder is up to you, as workflows vary from project to project. Ultimately this decision is up to you:

Benefits of checking in the Pods directory:

  • After cloning the repo, the project can immediately build and run, even without having CocoaPods installed on the machine. There is no need to run pod install, and no Internet connection is necessary.
  • The Pod artifacts (code/libraries) are always available, even if the source of a Pod (e.g. GitHub) were to go down.
  • The Pod artifacts are guaranteed to be identical to those in the original installation after cloning the repo.

Benefits of ignoring the Pods directory:

  • The source control repo will be smaller and take up less space.
  • As long as the sources (e.g. GitHub) for all Pods are available, CocoaPods is generally able to recreate the same installation. (Technically there is no guarantee that running pod install will fetch and recreate identical artifacts when not using a commit SHA in the Podfile. This is especially true when using zip files in the Podfile.)
  • There won’t be any conflicts to deal with when performing source control operations, such as merging branches with different Pod versions.