pod update <PodName> instead of a bare pod update to upgrade only that target library while keeping unrelated pods pinned to Podfile.lock. If transitive sub-dependencies still shift, pin the exact target version in your Podfile and run pod install so the resolver leaves every other locked version untouched.Why this happens
CocoaPods separates dependency resolution into two distinct workflows controlled by Podfile and Podfile.lock. When you run pod update with no arguments, CocoaPods ignores Podfile.lock across your entire Xcode workspace and upgrades every listed library to the newest version allowed by your Podfile constraints. In large iOS or macOS projects—especially those with loose version rules or none at all—this triggers unintended major or minor bumps across dozens of unrelated frameworks.
Even when you run pod update SomePodName, you can still see other entries change inside Podfile.lock. This happens for three main reasons:
- Shared or transitive dependencies: If
SomePodNamedepends on a helper library underneath the hood, upgradingSomePodNameallows CocoaPods to upgrade its underlying dependencies if the newer podspec requires them or if no other pod locks them down. - Outdated CocoaPods installations: Very old versions of the
cocoapodsRuby gem lacked targeted single-pod resolution or handled subspecs inconsistently across workspace targets. - Using
pod updateto install newly added pods: Many developers runpod updateafter adding a brand-new line toPodfile, inadvertently refreshing existing pods whenpod installwas the right command.
How to fix it
1. Run pod update with the exact pod name
To update a single pod to the newest version permitted by your Podfile without unlocking unrelated libraries, pass the case-sensitive pod name directly to pod update from your Xcode project directory:
pod update Alamofire
If your team manages Ruby gems with Bundler (check for a Gemfile in the root of your repository), prefix the command with bundle exec so you use the exact CocoaPods binary expected by the project:
bundle exec pod update Alamofire
When you pass a pod name, CocoaPods ignores the version recorded in Podfile.lock for that specific pod, searches the spec repository for the highest version matching your Podfile rule, and keeps unrelated top-level pods locked to their existing versions.
If targeted updates fail or upgrade unrelated top-level pods anyway, check your CocoaPods version first:
pod --version
Upgrade CocoaPods using whichever package manager installed it on your Mac:
# If installed via Homebrew
brew upgrade cocoapods
# If installed via RubyGems
sudo gem install cocoapods
2. Pin the target version in Podfile and run pod install
Running pod update SomePodName tells CocoaPods to find the latest allowed version of SomePodName, which can also pull newer versions of its transitive dependencies even when the current sub-dependencies would still work. If you want the smallest possible change in Podfile.lock, edit the version constraint explicitly in Podfile and run pod install instead.
Understanding how pod install evaluates Podfile.lock is the key here. Suppose your Podfile contains an optimistic operator:
platform :ios, '16.0'
use_frameworks!
target 'MyApp' do
pod 'Kingfisher', '~> 7.8'
pod 'SnapKit', '~> 5.6'
end
If Podfile.lock currently pins Kingfisher at 7.8.1 and you simply run pod install, nothing changes—because 7.8.1 already satisfies '~> 7.8'. However, if you tighten or bump the requirement in Podfile to a specific version higher than the locked one:
target 'MyApp' do
pod 'Kingfisher', '7.11.0'
pod 'SnapKit', '~> 5.6'
end
Now run pod install:
pod install
Because 7.8.1 no longer satisfies '7.11.0', CocoaPods resolves Kingfisher to 7.11.0 while strictly preserving every existing entry in Podfile.lock—including shared dependencies—unless 7.11.0‘s podspec explicitly demands a newer minimum version.
If CocoaPods prints [!] CocoaPods could not find compatible versions for pod "Kingfisher", your local spec cache is out of date. Fetch fresh podspec metadata without unlocking any locked versions by adding --repo-update:
pod install --repo-update
3. Install a newly added pod without touching existing ones
If you are adding a new library to your Podfile rather than upgrading an existing one, never run pod update. Add the new pod entry to your Podfile and run pod install with --no-repo-update for the fastest offline resolution:
pod install --no-repo-update
The --no-repo-update flag forces CocoaPods to use your Mac’s local spec cache and prevents any remote spec refresh. Every previously installed pod stays at the exact commit or semantic version recorded in Podfile.lock.
If your local cache does not yet have the podspec for the new library, drop the flag and run a standard pod install. Even without --no-repo-update, pod install never upgrades pods that are already listed in Podfile.lock as long as their locked versions still satisfy your Podfile.
4. Update related subspecs together and verify Podfile.lock
Many SDKs split functionality across subspecs that must share the exact same underlying core version. For example, if your Podfile declares multiple subspecs from the same parent pod:
target 'MyApp' do
pod 'Firebase/Analytics'
pod 'Firebase/Crashlytics'
end
Trying to update only one subspec often triggers a version conflict (CocoaPods could not find compatible versions) because the remaining subspecs stay pinned to an older core dependency in Podfile.lock. Update all related subspecs in a single command by passing each name separated by spaces:
pod update Firebase/Analytics Firebase/Crashlytics
After any pod command finishes, always inspect Podfile.lock before opening your .xcworkspace in Xcode:
git diff Podfile.lock
Check the PODS: section at the top of the diff. You should only see version changes for the pod you targeted and any direct child dependencies required by its new release. If an unrelated pod changed, run git checkout Podfile.lock && pod install to roll back immediately.
How to prevent it
- Commit
Podfile.lockto Git: WithoutPodfile.lockchecked into version control, every teammate and CI runner resolves fresh versions from scratch, turning routinepod installruns into accidental updates. - Use optimistic version constraints (
~>): Avoid open-ended declarations likepod 'Alamofire'with no version string. Specify~> 5.9(allows5.9.xand minor bumps under6.0) or~> 5.9.0(allows only5.9.xpatch releases). - Default to
pod installin daily workflows: Reservepod update <PodName>strictly for intentional dependency bumps, and avoid running barepod updateexcept during planned maintenance sprints. - Standardize the CocoaPods binary with a
Gemfile: Commit aGemfileandGemfile.lockspecifying thecocoapodsversion sobundle exec pod installproduces identical lockfiles across every developer’s Mac.
FAQ
Why did pod update PodName --no-repo-update fail to find the newest version?
Passing --no-repo-update blocks CocoaPods from checking the CDN or remote spec repository for newly published releases. If the version you want was released after your last cache refresh, run pod update PodName without that flag so CocoaPods can download the latest podspec.
What is the difference between pod install --repo-update and pod update?
pod install --repo-update only refreshes your Mac’s local index of available podspecs while still obeying every locked version inside Podfile.lock. By contrast, pod update refreshes the spec index and actively ignores Podfile.lock, upgrading your installed pods to the newest compatible versions.
Can I downgrade a single pod without affecting other dependencies?
Yes. Set the exact older version string in your Podfile (for example, pod 'Lottie-ios', '4.3.0') and run pod install. CocoaPods will downgrade only that pod to match the explicit constraint while leaving the rest of Podfile.lock intact.
Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.
