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.


Read more »

Latest entries

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…

Broken devpi / pip builds with PEP-503 HOWTO fix

Using devpi-server 3.1.x with pip 8.1.2 breaks builds because pip is now a correct implementation of PEP-503.  The presence of dots in the path breaks devpi 3.1.x builds (or earlier versions).  Here is a quick…

Dodging Gratuitous Email Spying - ProtonMail

ProtonMail is a freemium service for secure communications that targets novice and advance users.  How is ProtonMail better than Gmail or other services? What are its limitations? How to set it up? The rest of this…

Your Startup's Vision and the Legend of the Fury Road

A film legend is a pre-production write up, the equivalent to Silicon Valley's "business plan on the back of a napkin," that lists the main points of a story.  Clarity of thought, focus, and precise execution are t…

UNIX: When Sloppy Works Better

UNIX sloppy command usage can render better results than mastery.  This could be a huge win in Dev Ops situations.  The best way to evaluate how good an implementation is, is to ensure that it works, it does t…