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](https://hackernoon.com/tagged/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](https://hackernoon.com/tagged/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_ the`Podfile.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](https://guides.cocoapods.org/using/the-podfile.html) 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_](https://www.interceptip.com/contact/) _(formerly Control F1), look her up on_ [_Linked In_](https://www.linkedin.com/in/gabrielle-earnshaw-29284120/) _or say ‘hi’ on twitter at_ [_@GabEarnsh_](https://twitter.com/GabEarnsh)_._

#### Read more of my stories:

[**Implementing a Sketch text design system in your Xcode project**  
_Change text styles in Xcode as easily as in your design file_medium.com](https://medium.com/sketch-app-sources/implementing-a-sketch-text-design-system-in-your-xcode-project-5c7cb61809a4 "https://medium.com/sketch-app-sources/implementing-a-sketch-text-design-system-in-your-xcode-project-5c7cb61809a4")[](https://medium.com/sketch-app-sources/implementing-a-sketch-text-design-system-in-your-xcode-project-5c7cb61809a4)

[**Painless icon generation for iOS apps with Sketch and Xcode — Part 1**  
_How to create all of your icon sizes in seconds_medium.com](https://medium.com/sketch-app-sources/painless-icon-generation-for-ios-apps-with-sketch-and-xcode-part-1-a169794aac8b "https://medium.com/sketch-app-sources/painless-icon-generation-for-ios-apps-with-sketch-and-xcode-part-1-a169794aac8b")[](https://medium.com/sketch-app-sources/painless-icon-generation-for-ios-apps-with-sketch-and-xcode-part-1-a169794aac8b)

[**Next-level Swift unit tests using the builder pattern**  
_Make unit tests easier to code, review and maintain_medium.com](https://medium.com/swift2go/next-level-swift-unit-tests-using-the-builder-pattern-d242c447d10c "https://medium.com/swift2go/next-level-swift-unit-tests-using-the-builder-pattern-d242c447d10c")[](https://medium.com/swift2go/next-level-swift-unit-tests-using-the-builder-pattern-d242c447d10c)

Demystifying Pod Install and Pod Update

Too Long; Didn't Read

Company Mentioned

@GabEarnsh

RELATED STORIES