Many people starting with CocoaPods seem to think
pod install is only used the first time you setup a project using CocoaPods and
pod update is used afterwards. But that's not the case at all.
The aim of this guide is to explain when you should use
pod install and when you should use
pod installto install new pods in your project. Even if you already have a
pod installbefore; so even if you are just adding/removing pods to a project already using CocoaPods.
pod update [PODNAME]only when you want to update pods to a newer version.
<Detailed presentation of the commands
Note: the vocabulary of
updateis not actually specific to CocoaPods. It is inspired by a lot of other dependency managers like bundler, RubyGems or composer, which have similar commands, with the exact same behavior and intents as the one described in this document.
This is to be used the first time you want to retrieve the pods for the project, but also every time you edit your Podfile to add, update or remove a pod.
- Every time the
pod installcommand is run — and downloads and install new pods — it writes the version it has installed, for each pods, in the
Podfile.lockfile. This file keeps track of the installed version of each pod and locks those versions.
- When you run
pod install, it only resolves dependencies for pods that are not already listed in the
- For pods listed in the
Podfile.lock, it downloads the explicit version listed in the
Podfile.lockwithout trying to check if a newer version is available
- For pods not listed in the
Podfile.lockyet, it searches for the version that matches what is described in the
pod 'MyPod', '~>1.2')
- For pods listed in the
When you run
pod outdated, CocoaPods will list all pods which have newer versions than the ones listed in the
Podfile.lock (the versions currently installed for each pod). This means that if you run
pod update PODNAME on those pods, they will be updated — as long as the new version still matches the restrictions like
pod 'MyPod', '~>x.y' set in your
When you run
pod update PODNAME, CocoaPods will try to find an updated version of the pod
PODNAME, without taking into account the version listed in
Podfile.lock. It will update the pod to the latest version possible (as long as it matches the version restrictions in your
If you run
pod update with no pod name, CocoaPods will update every pod listed in your
Podfile to the latest version possible.
pod update PODNAME, you will be able to only update a specific pod (check if a new version exists and update the pod accordingly). As opposed to
pod install which won't try to update versions of pods already installed.
When you add a pod to your
Podfile, you should run
pod install, not
pod update — to install this new pod without risking to update existing pod in the same process.
You will only use
pod update when you want to update the version of a specific pod (or all the pods).
<Commit your Podfile.lock
As a reminder, even if your policy is not to commit the
Pods folder into your shared repository, you should always commit & push your
Otherwise, it would break the whole logic explained above about
pod install being able to lock the installed versions of your pods.
Here is a scenario example to illustrate the various use cases one might encounter during the life of a project.
<Stage 1: User1 creates the project
user1 creates a project and wants to use pods
C. They create a
Podfile with those pods, and run
This will install pods
C, which we'll say are all in version
Podfile.lock will keep track of that and note that
C are each installed as version
Incidentally, because that's the first time they run
pod installand the
Pods.xcodeprojproject doesn't exist yet, the command will also create the
.xcworkspace, but that's a side effect of the command, not its primary role.
<Stage 2: User1 adds a new pod
Later, user1 wants to add a pod
D into their
They should thus run
pod install afterwards, so that even if the maintener of pod
B released a version
1.1.0 of their pod since the first execution of
pod install, the project will keep using version
1.0.0 — because user1 only wants to add pod
D, without risking an unexpected update to pod
That's where some people get it wrong, because they use
pod updatehere — probably thinking this as "I want to update my project with new pods"? — instead of using
pod install— to install new pods in the project.
<Stage 3: User2 joins the project
Then user2, who never worked on the project before, joins the team. They clone the repository then use
The contents of
Podfile.lock (which should be committed onto the git repo) will guarantee they will get the exact same pods, with the exact same versions that user1 was using.
Even if a version
1.2.0 of pod
C is now available, user2 will get the pod
C in version
1.0.0. Because that's what is registered in
C is locked to version
1.0.0 by the
Podfile.lock (hence the name of this file).
<Stage 4: Checking for new versions of a pod
Later, user1 wants to check if any updates are available for the pods. They run
pod outdated which will tell them that pod
B have a new
1.1.0 version, and pod
C have a new
1.2.0 version released.
user1 decides they want to update pod
B, but not pod
C; so they will run
pod update B which will update
B from version
1.0.0 to version
1.1.0 (and update the
Podfile.lock accordingly) but will keep pod
C in version
1.0.0 (and won't update it to
<Using exact versions in the
Podfile is not enough
Some might think that by specifying exact versions of their pods in their
pod 'A', '1.0.0', is enough to guarantee that every user will have the same version as other people on the team.
Then they might even use
pod update, even when just adding a new pod, thinking it would never risk to update other pods because they are fixed to a specific version in the
But in fact, that is not enough to guarantee that user1 and user2 in our above scenario will always get the exact same version of all their pods.
One typical example is if the pod
A has a dependency on pod
A2 — declared in
dependency 'A2', '~> 3.0'. In such case, using
pod 'A', '1.0.0' in your
Podfile will indeed force user1 and user2 to both always use version
1.0.0 of the pod
user1 might end up with pod
3.4(because that was
A2's latest version at that time)
- while when user2 runs
pod installwhen joining the project later, they might get pod
3.5(because the maintainer of
A2might have released a new version in the meantime).
That's why the only way to ensure every team member work with the same versions of all the pod on each's computer is to use the
Podfile.lock and properly use
pod install vs.