The definitive guide to installing and updating pods

The difference between pod install and pod update is subtle, and it isn’t always clear which you should use. But having a good understanding of what these commands do gives you much finer control over how dependencies are managed in your project, so it’s worth knowing the difference.

In the first part of this article I’ll give you a list of recipes showing whether you should run pod install or pod update in some common situations. Then in the second part I’ll explain why the different commands do different things, and how CocoaPods uses the Podfile.lock file to make it all happen.

Part 1: Recipes

For these recipes to work, ensure that Podfile and Podfile.lock are committed to source control.

You are setting CocoaPods up in a project for the first time and have created your Podfile

pod install

This will install the latest version* of each of the pods you specified in your new Podfile. It will also create a MyProject.xcworkspace file if one didn’t already exist.

You added a new pod to your Podfile

pod install

This will install the latest version* of any new pods added to your Podfile, leaving your other pods unchanged.

If you were to run pod update instead, it would install the new pods and update each of your existing pods to its latest version*.

You want to get the latest version of all pods in your Podfile

pod update

This will go through all of your pods and make sure that the latest version* of each is installed in your project.

You want to get the latest version of only one pod in your Podfile

pod update SomePod

This will make sure that the latest version* of the pod you specify is installed, whilst leaving your other pods unchanged.

You are working with a development pod and want to get your latest changes

pod update MyDevelopmentPod

This will make sure that the latest version of your pod is installed, whilst leaving your other pods unchanged.

You have downloaded the source for an existing project that uses CocoaPods

pod install

This will install all pods in the Podfile at the exact versions that were previously installed in this cut of the source code.

If you were to run pod update instead, it would install the latest version* of each of the pods in the Podfile. This could prevent the project from building if the latest versions weren’t compatible with other code in the project. I’d recommend running pod install to get the code building, then updating pods as necessary in a controlled manner.

You are writing a script to build a project on a build server

pod install

This will install all pods in the Podfile at the exact versions that were installed in the version being built. This is important for a stable build, because these are the versions that the code was developed against, and it means that every build of that cut of code will use the same pod versions. If you were to use pod update instead, your build could potentially use different versions of pods each time it builds.

Xcode is reporting weird build errors relating to pods

This occasionally happens after updating pods, or after switching between branches of a project that contain the same pods at different versions.

Delete the /Pods directory, then run pod install

This will reinstall all pods in the Podfile at the exact versions that were previously installed, and is usually enough to straighten out any issues that Xcode can find itself with.

Sometimes people suggest deleting the /Pods directory and thePodfile.lock file, then running pod install. This will solve any issues with Xcode, but will also upgrade each of the pods in the Podfile to its latest version*.

Part 2: How it works

The difference between pod install and pod update lies in how they interact with the Podfile.lock file. This file is used to store the exact version of each pod that is currently installed in your project.

The easiest way to understand how it works is to look at the following diagram (disclaimer: this is a simple schematic rather than an accurate technical diagram).

pod update

pod update ignores Podfile.lock when checking for versions. It looks for the the latest available version* of a pod, and installs it if it isn’t already installed.

pod install

pod install looks in Podfile.lock first when checking for versions. If a version of the pod is listed in Podfile.lock, it will install that exact version. If that pod isn’t listed in Podfile.lock (or if Podfile.lock doesn’t exist yet), it will behave as for pod update, i.e. it finds the latest available version* and installs it.

In both cases, CocoaPods then updates Podfile.lock with any new version numbers that were installed.

This is what allows you to use pod versions consistently across different installs of a project (i.e. when installing from a repository, across multiple team members, or on a build server), and is why Podfile.lock should be committed to source control.

Summary

In this article I’ve given recipes showing whether to run pod install or pod update in a number of common situations. I’ve then described how and why the two commands work in different ways. If you’ve found it useful, please give it a clap and / or share, and follow me for other useful articles.

[*] By latest version I mean latest version that satisfies the requirements and dependencies in your Podfile. See the section on Specifying pod versions in the official guide to The Podfile for more information.

Gabrielle is an iOS specialist who leads technical teams creating mobile apps. For app development and more, please contact her at Intercept IP (formerly Control F1), look her up on Linked In or say ‘hi’ on twitter at @GabEarnsh.

Read more of my stories: