Eugene Ciurana Official Site

No-nonsense CocoaPods Upgrade HOWTO

CocoaPods is great for managing complex OS X and iOS projects with lots of external dependencies.  The authors, however, decided on a policy of breaking backward compatibility with every previous release, disowning support for older versions as soon as a new one is available, and forcing everyone to upgrade as soon as possible.  This HOWTO shows how to have a smooth CocoaPods upgrade.


CocoaPods 1.0 broke the Podfile format and internal pod model on purpose, aiming to provide future stability as new features are added. For the end user, this means managing the upgrade for all projects ASAP.  These results in two immediate actions:

  1. Update the Podfiles and Podspecs for every related project to ensure that they are compatible with the new release
  2. Update the CocoaPods installation to the latest release

This HOWTO addresses the CocoaPods installation and its relationship with Xcode workspaces.


The CocoaPods instructs users to deploy using:

sudo gem install cocoapods

This is a bad idea because changes become global to the Mac.  CocoaPods relies on Ruby, and it could be affected by (or affect) other global Ruby packages.  Instead, use Homebrew to install a Ruby run-time in user space, along with CocoaPods.  Safer installation, all in user space.

Try this instead:

brew update && brew upgrade
[[ $(which ruby) == "/usr/local/bin/ruby" ]] || brew install ruby
gem install cocoapods
# gem install cocoapods
# Fetching: cocoapods-1.0.0.gem
# Successfully installed cocoapods-1.0.0
# Parsing documentation for cocoapods-1.0.0
# Installing ri documentation for cocoapods-1.0.0
# 1 gem installed

Preparing the environment

CocoaPods repositories, caches, and overall Xcode configuration must be reset before using the upgraded pod command.  The cleanest, fastest way to accomplish this:

rm -Rfv "$HOME/Library/Caches/CocoaPods"
rm -Rfv "$HOME/Library/Developers/Xcode/DerivedData"
rm -Rfv "$HOME/.cocoapods"

The initial build will take a long time, since everything will have to be rebuilt, but you'll be guaranteed that all the CocoaPod internal dependencies are resolved.  We tried building without nuking the Xcode derived data or the private CocoaPods directory, and got some bizarre dependency errors.  This prepping prevents those.

First build after upgrade

The first build must update the Xcode workspace as well as the pods.  The fastest way to do this is to delete the Podfile.lock, deintegrate the project, install, and build.  If the new Podfile is up-to-date, and if the installation was correct, the project can be build and you can go home early.

cd your_project
rm -f Podfile.lock
pod deintegrate
pod install && open YourProject.xcworkspace
# Go build now!

Xcode should build the project without further issues, and all CocoaPod dependencies must be satisfied and correct.


Building the projects will result in errors that were non-existent prior to the upgrade.  These result from Xcode, the Podfiles, the podspecs, and the caches or repos being out of sync.  Here's how you can fix some of the ones we found.

Incorrect packages included

  1. Check that the Podfile.podspec is up-to-date to include the latest version of the code
  2. Delete the $HOME/.cocoapods and Caches/CocoaPods directories

Linker complains that lPod is missing

  1. Exit Xcode
  2. Go to the project's directory
  3. Deintegrate the project, then install
  4. Open the Xcode workspace, build again

codesign fatal exit 1

This one results from including a framework pod in the build.  To fix, tell the Podfile to link frameworks instead of static libraries:

source ''

Missing pods that are part of the same project

It's easy to lose track of dependencies for pods with all the building/removing/nuking/rebuilding/coffee/argh! due to the upgrade.  Our shop requires two service pods, plus the main project's pods, and they have to be built in order to satisfy all dependencies.  If Xcode complains that a local dependency isn't satisfied, review your build process and ensure that all prerequisites are satisfied.


Share your comments, questions, etc. via Twitter and/or Facebook.


Written by Eugene Ciurana on Thursday May 19, 2016
Permalink -

« Broken devpi / pip builds with PEP-503 HOWTO fix - Gijón Style Cherry Ice Cream »