CocoaPods - codepath/ios_guides GitHub Wiki

CocoaPods is a dependency management system for iOS (and other Cocoa-based) projects. It is very similar in function and usage to npm for JavaScript and Bundler for Ruby.

Status (2026): The CocoaPods Trunk (the central index that publishes new pod releases) goes permanently read-only on December 2, 2026. Existing builds will keep working — the Specs repo and CDN remain available — but no new pods or version updates will be published through Trunk after that date. For new projects, prefer Swift Package Manager (SPM), Apple's first-party, Xcode-integrated dependency manager. CocoaPods is still appropriate for existing projects and for pods that haven't shipped an SPM package yet.

CocoaPods is packaged as a Ruby gem. Since Ruby comes with new OS X installations, you can install CocoaPods simply by running the following commands in a terminal:

# Install Xcode Component Tools
xcode-select --install
# Install CocoaPods gem
sudo gem install cocoapods

Step 1: Install Brew

# Update your xcode dev tools and wait for installation
xcode-select --install

# Install Brew (package manager)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add 'brew' as a terminal command (change {USER_NAME})
echo 'eval $(/opt/homebrew/bin/brew shellenv)' >> /Users/{USER_NAME}/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Verify Installation
which brew

Step 2: Install cocoapods using Brew

brew install cocoapods

# Verify the installation from brew and get the Version number:
brew info cocoapods
# ^example output: cocoapods: stable 1.16.2 (bottled)

# Go to your project directory
cd path/to/project

# Install pods (REMEMBER to run this in your project folder)
pod init
pod install

Note: Older guides recommended prefixing every command with arch -x86_64 and force-installing the ffi gem under Rosetta. With current Homebrew + CocoaPods 1.16.x, brew install cocoapods provides a native arm64 install and these workarounds are no longer needed in the main install path — they are kept under Common Issues below only as troubleshooting fallback for setups that ended up with x86_64 Ruby. See Moncef Belyamani's native ffi guide for the modern native-Ruby setup.

Note: There are alternate instructions if you need to perform a sudo-less install or install a beta version of CocoaPods.

You can find available Pods using the search box on the official CocoaPods site or using the Wantedly search. When you find a pod you want to add to your project, follow these steps:

You only need a single Podfile per project. The Podfile is a plain text file where you can add multiple pods.

• From a terminal in the root directory of your project, run...

  pod init

Please refer to these steps if you encounter issues when installing cocoapods.

On your terminal

Install ffi

If you get an error saying something like this: "need to install using arch" try this sudo arch -x86_64 gem install ffi

Re-installing dependency

If "pod install" doesn't work, try this arch -x86_64 pod install

If you are having issues installing Ruby, gems, or cocoapods, try these:

Install RVM

Install Brew

Check out this stackoverflow in case you encounter even more issues.

• pod init generates a template Podfile that looks roughly like the example below. Edit it to declare your app's minimum iOS deployment target and the pods you want to install:

  # Uncomment the next line to define a global platform for your project.
  # Set this to the same iOS version as your app target's iOS Deployment Target
  # (Build Settings → Deployment → "iOS Deployment Target", or General → "Minimum Deployments" in Xcode 14+).
  # platform :ios, '9.0'
  
  # NOTE: Change the string below to the name of your project
  target 'YOUR_APP_NAME' do
    # Build pods as dynamic frameworks (see the "Framework vs. Static Library Linkage"
    # section below for static vs. dynamic trade-offs).
    use_frameworks!
  
    # Pods for MyApp — pin a specific version when you want reproducible builds;
    # omit the version to track the latest release.
    pod 'AlamofireImage'
  
  end

• The platform :ios, '9.0' line is the placeholder value pod init emits; replace 9.0 with your project's actual minimum deployment target before uncommenting it. Many modern pods require iOS 13 or later — check each pod's spec.

• Refer to the Podfile documentation to see versioning options and more complex use cases.

• From a terminal in the root directory of your project, run...

  pod install --verbose

• CocoaPods currently forks the spec repo. If the pod install fails, you may need to update your current specs:

  pod repo update

• Close the project (MyApp.xcodeproject) if you have it open and open the workspace (MyApp.xcworkspace).

• CocoaPods creates an additional project for all the dependencies so you need to open the .xcworkspace from now on (which will contain your original project and the pods project).:

  <Workspace version = "1.0">
  <FileRef location = "group:ParseLab.xcodeproj"></FileRef>
  <FileRef location = "group:Pods/Pods.xcodeproj"></FileRef>
  </Workspace>     

CocoaPods has first-class Swift support: since CocoaPods 1.5.0 you no longer need use_frameworks! just to consume a Swift pod, so the directive is no longer a Swift-vs-Objective-C choice. The decision worth thinking about today is how each pod is linked into your app.

By default (when no use_frameworks! directive is present), CocoaPods links Pods as static libraries. Adding use_frameworks! builds Pods as dynamic frameworks instead. Since CocoaPods 1.9.0, you can also choose the linkage explicitly:

target 'YOUR_APP_NAME' do
  # Plain `use_frameworks!` defaults to :dynamic
  use_frameworks!

  # Or build pods as static frameworks (modular headers are enabled automatically)
  # use_frameworks! :linkage => :static

  pod 'AlamofireImage'
end

Choosing between them:

• Dynamic frameworks share code across multiple app targets at runtime and are sometimes required by pods (e.g., those that include resources, or that themselves embed dynamic dependencies).
• Static linking typically reduces app launch time and is the recommended choice for libraries that are only used by a single target. Mixing static and dynamic linkage of the same pod across targets can produce duplicate-symbol errors at link time, so pick a consistent strategy per dependency. Firebase documents the trade-offs and pitfalls in more detail.

What lets Swift import an Objective-C pod without a bridging header is modular headers, not the linkage choice itself. use_frameworks! enables modular headers as a side effect, but you can also enable them independently with use_modular_headers! (all pods) or :modular_headers => true (per pod). If a particular Objective-C pod fails to build with use_frameworks!, its headers likely aren't modular — file an issue with the pod's maintainers, or drop use_frameworks! and use a bridging header for the affected target.

If you want to fully remove all traces of CocoaPods from your Xcode project, there's a tool that can do this for you. Run the following command to install the tool:

sudo gem install cocoapods-deintegrate

And then navigate to the directory that contains your project (the same directory that has the .xcodeproj and Podfile files) and run the following command:

pod deintegrate

Note: This will remove all traces of CocoaPods from your project, but will leave 3 files hanging around on disk. If you want to fully remove all traces of CocoaPods, you'll also want to delete the following 3 files: Podfile, Podfile.lock, and *.xcworkspace.

Swift Package Manager (SPM) is Apple's first-party dependency manager, built directly into Xcode (supported for iOS projects since Xcode 11). It requires no external installation and is the default choice for new iOS projects — most major libraries (Alamofire, Kingfisher, RxSwift, SnapKit, and others) now publish SPM packages, and Firebase has announced its CocoaPods deprecation in favor of SPM. You add packages via Xcode's File → Add Package Dependencies… menu. Reach for CocoaPods when a specific dependency hasn't shipped an SPM package, or when an existing project already has a working Podfile you don't want to migrate yet.

Carthage is a third-party dependency manager that produces pre-built frameworks you integrate into your Xcode project manually. It avoids mutating your project file but has seen reduced adoption as SPM has matured.

• https://cocoapods.org
• https://github.com/Carthage/Carthage