How to Downgrade CocoaPods to an Older Version

Why this happens

CocoaPods updates frequently introduce changes to how Xcode workspace targets, build configurations, and xcconfig files are generated. When an updated CocoaPods release changes internal DSL parsing or modifies Xcode project integration, existing projects may fail to compile, produce duplicate symbol warnings, or break custom script phases.

Another common cause is team or continuous integration (CI) divergence. If your build pipeline runs CocoaPods 1.12.1 and a developer updates locally to 1.15.0, the resulting Podfile.lock and workspace configuration changes can cause merge conflicts, CI build failures, or unexpected checksum mismatches.

Legacy iOS projects often rely on third-party pods or plugins that were abandoned before adopting newer CocoaPods requirements. In these cases, installing or rolling back to an older CocoaPods release is necessary to maintain build stability without refactoring legacy dependencies.

How to fix it

1. Install a specific version alongside your current version

RubyGems allows multiple versions of the same gem to exist on your machine simultaneously. You do not need to uninstall your current CocoaPods installation if you only need an older release for a specific project.

First, check which versions you currently have installed:

gem list cocoapods

Install the specific older version using the -v flag. If you are using your Mac’s system Ruby, you may need sudo, though using a Ruby version manager (rbenv or mise) is strongly recommended to avoid root permissions:

sudo gem install cocoapods -v 1.11.3

Once installed, you can invoke that specific version for any command by wrapping the version number in underscores directly after pod:

pod _1.11.3_ install

To run a pod update or check the environment for that specific release:

pod _1.11.3_ env

This approach allows you to work across multiple projects requiring different CocoaPods releases on the same machine without modifying your global default environment.

2. Uninstall newer versions to force an absolute downgrade

If your scripts, build systems, or Xcode build phase hooks call pod without version specifiers, having newer versions installed may cause your system to default to the newest binary. In this scenario, remove the newer versions completely.

Run the uninstall command:

sudo gem uninstall cocoapods

If you have multiple versions installed, RubyGems will display an interactive prompt:

Select gem to uninstall:
 1. cocoapods-1.15.2
 2. cocoapods-1.11.3
 3. All versions
> 1

Select the version number you want to remove. Alternatively, you can uninstall a specific version directly by passing the -v flag:

sudo gem uninstall cocoapods -v 1.15.2

If you also need to remove associated dependencies like cocoapods-core or cocoapods-downloader that might conflict with older releases, uninstall them explicitly or select “All versions” when prompted, then reinstall your target version clean:

sudo gem install cocoapods -v 1.11.3

Verify that the target version is now your system default:

pod --version

3. Handle Homebrew installations

If you originally installed CocoaPods using Homebrew (brew install cocoapods), RubyGems commands will not alter or downgrade that binary. Homebrew typically maintains only the latest stable formula, making older versions difficult to install directly through brew.

First, verify how CocoaPods is installed:

which pod

If the output points to /opt/homebrew/bin/pod or /usr/local/bin/pod, it was installed via Homebrew. Uninstall the Homebrew formula:

brew uninstall cocoapods

After removing the Homebrew package, install the target version via RubyGems:

sudo gem install cocoapods -v 1.12.1

Ensure that your shell’s PATH finds the gem executable before running commands. You can verify the active executable path by running which pod again.

4. Lock versions per-project using Bundler (Recommended)

Managing global gem versions across teams frequently leads to conflicts when different projects require different releases. The industry standard solution for iOS projects is to manage CocoaPods via Bundler.

Install Bundler if it is not already available:

gem install bundler

In the root directory of your project (alongside your Podfile), create a file named Gemfile without any file extension:

source 'https://rubygems.org'

gem 'cocoapods', '1.12.1'

Install and lock the specified version:

bundle install

This creates a Gemfile.lock file that locks the exact CocoaPods version and all sub-dependencies (cocoapods-core, xcodeproj, claide). Commit both Gemfile and Gemfile.lock to your Git repository.

Whenever you run CocoaPods commands for this project, run them through Bundler:

bundle exec pod install

Bundler ensures that every developer on the team and your CI service use the exact same CocoaPods binary, completely removing the need to manually downgrade or align global Mac environments.

How to prevent it

• Adopt Bundler for all projects: Always define CocoaPods in a Gemfile and commit Gemfile.lock to source control so local updates never affect project builds unexpectedly.
• Avoid brew install cocoapods: Prefer RubyGems managed by a version manager like rbenv or asdf instead of Homebrew to ensure version pinning is possible.
• Pin the CocoaPods version in your Podfile: Add an assertion to the top of your Podfile to prevent team members from running an incompatible version:
  ruby
pod_version = Gem::Version.new(CocoaPods::VERSION)
required_version = Gem::Version.new('1.12.1')
raise "Please use CocoaPods #{required_version}" unless pod_version == required_version
• Audit CI workflows: Ensure your CI pipeline invokes bundle exec pod install rather than a global pod install command.

FAQ

Can I keep multiple versions of CocoaPods installed at the same time?

Yes. RubyGems supports multiple versions simultaneously. You can install an older release using gem install cocoapods -v <version> and call it directly with pod _<version>_ install without removing other versions.

Why does pod --version still show the new version after installing an older one?

RubyGems defaults to executing the newest installed gem version when invoked without version specifiers. To make the older version the default, uninstall the newer version using gem uninstall cocoapods -v <newer_version>.

Why does pod _version_ install fail with a gem activation error?

This occurs when a sub-dependency (such as cocoapods-core or xcodeproj) has conflicting newer versions installed that are incompatible with the older CocoaPods gem. Using Bundler with a Gemfile isolates the dependency tree and avoids gem activation conflicts.