Fix: Unable to Update a Single Pod Without Changing Others in Xcode

Fix: Unable to Update a Single Pod Without Changing Others in Xcode

Written by

in

Quick answer: Run 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 SomePodName depends on a helper library underneath the hood, upgrading SomePodName allows 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 cocoapods Ruby gem lacked targeted single-pod resolution or handled subspecs inconsistently across workspace targets.
  • Using pod update to install newly added pods: Many developers run pod update after adding a brand-new line to Podfile, inadvertently refreshing existing pods when pod install was 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.lock to Git: Without Podfile.lock checked into version control, every teammate and CI runner resolves fresh versions from scratch, turning routine pod install runs into accidental updates.
  • Use optimistic version constraints (~>): Avoid open-ended declarations like pod 'Alamofire' with no version string. Specify ~> 5.9 (allows 5.9.x and minor bumps under 6.0) or ~> 5.9.0 (allows only 5.9.x patch releases).
  • Default to pod install in daily workflows: Reserve pod update <PodName> strictly for intentional dependency bumps, and avoid running bare pod update except during planned maintenance sprints.
  • Standardize the CocoaPods binary with a Gemfile: Commit a Gemfile and Gemfile.lock specifying the cocoapods version so bundle exec pod install produces 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.

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.