How to Install or Downgrade to an Older CocoaPods Version in Ruby

By the end of this page, you will understand how Ruby gem versioning works for CocoaPods, how to install a specific CocoaPods version, how to run that exact version, and how teams usually keep CocoaPods versions consistent across projects.

CocoaPods is distributed as a Ruby gem, so installing or downgrading it means working with Ruby's gem version system.

When people say they want to downgrade CocoaPods, they usually mean one of these things:

• install an older gem version,
• make that older version the one they use in the terminal,
• or ensure a project always runs a specific version.

The key idea is that multiple gem versions can exist on the same machine. You do not always have to remove the newer one first. Instead, you can install a specific version and then run that exact version when needed.

This matters because many iOS projects depend on tool versions being consistent. A different CocoaPods version can sometimes change:

• lockfile format,
• dependency resolution behavior,
• generated project files,
• warnings or build behavior.

So the real skill is not just installing an old version once. It is understanding how to pin and use the correct version intentionally.

Think of CocoaPods like a tool in a toolbox, and each version is a different edition of the same tool.

• 1.15.2 is one edition
• 1.14.3 is another edition
• 1.13.0 is another edition

Installing an older version does not necessarily throw the newer one away. It is more like putting another edition into the toolbox.

The important part is choosing which edition you actually pick up and use.

Ruby gems let you:

• keep multiple versions installed,
• ask for one exact version,
• and verify which one is being used.

For project work, this is similar to saying: "Use this exact screwdriver for this exact job."

The most common way to install a specific CocoaPods version is with gem install and the -v flag.

gem install cocoapods -v 1.14.3

This tells RubyGems to install exactly version 1.14.3 of the cocoapods gem.

To check installed versions:

gem list cocoapods

Example output:

*** LOCAL GEMS ***
cocoapods (1.15.2, 1.14.3)

To check which CocoaPods version runs by default:

pod --version

If you want to run a specific installed version explicitly, use gem's version execution through Bundler-friendly patterns or direct versioned invocation in Ruby environments. A common reliable team approach is to use a Gemfile:

source "https://rubygems.org"

gem "cocoapods", "1.14.3"

Then install and run it with Bundler:

bundle install
bundle exec pod --version
bundle exec pod install

This makes the project use the CocoaPods version declared in the Gemfile instead of whatever happens to be global on your machine.

If you want to uninstall a version:

gem uninstall cocoapods -v 1.15.2

That removes only the specified version.

Consider this command:

gem install cocoapods -v 1.14.3

Here is what happens step by step:

1. gem install tells RubyGems to install a package.
2. cocoapods is the gem name.
3. -v 1.14.3 means only version 1.14.3 is acceptable.
4. RubyGems downloads that version and its dependencies.
5. The gem becomes available in your Ruby environment.

Now suppose you run:

gem list cocoapods

RubyGems checks locally installed gems and prints the CocoaPods versions it finds.

Next, if you run:

pod --version

Your shell runs the pod executable it finds first in the current Ruby setup and PATH. This is why installing an older version is not always enough by itself: the shell may still use a different version.

That is why this project-level pattern is often safer:

source "https://rubygems.org"

gem "cocoapods", "1.14.3"

Then:

bundle install
bundle exec pod --version

Step by step:

1. Bundler reads the Gemfile.
2. It installs CocoaPods 1.14.3 if needed.
3. bundle exec runs commands in the context of that Gemfile.
4. pod now resolves to the pinned project version.
5. Everyone on the team can use the same version more reliably.

Trace example:

$ gem install cocoapods -v 1.14.3
Successfully installed cocoapods-1.14.3

$ gem list cocoapods
cocoapods (1.15.2, 1.14.3)

$ pod --version
1.15.2

$ bundle exec pod --version
1.14.3

This shows the difference between a global default version and a project-pinned version.

Using an older CocoaPods version is common in real development.

Working on an older iOS app

A legacy app may have been last maintained with a specific CocoaPods version. Using a newer one might change the Podfile.lock or generate different project settings.

Matching a CI environment

A continuous integration server may still use an older version. To avoid "works on my machine" issues, developers install and run the same version locally.

Reproducing a bug

If a problem appeared after upgrading CocoaPods, installing the previous version helps confirm whether the upgrade caused it.

Supporting multiple projects

You might work on:

• one app that needs 1.11.x
• another that needs 1.14.x
• a new app using the latest version

Instead of constantly uninstalling and reinstalling globally, you can keep multiple versions and use Bundler per project.

Team onboarding

New developers can clone a project, run bundle install, and immediately get the expected CocoaPods version without guessing.

In real codebases, developers usually avoid relying on a random global CocoaPods installation.

Common patterns include:

Pinning the version with Bundler

A Gemfile is the most common and safest approach.

source "https://rubygems.org"

gem "cocoapods", "1.14.3"

Then commands are run as:

bundle exec pod install
bundle exec pod update

Version consistency in CI

CI pipelines often run:

bundle install
bundle exec pod install

This prevents unexpected failures from machine-specific gem versions.

Guarding setup with documentation

Projects often include setup instructions like:

bundle install
bundle exec pod install

instead of simply telling developers to run pod install.

Early validation

Developers may check the active version before debugging dependency issues:

bundle exec pod --version

This is a simple validation step that saves time.

Avoiding global state problems

Global installs can differ between:

• system Ruby,
• Homebrew Ruby,
• rbenv or RVM Ruby,
• CI Ruby environments.

Using Bundler reduces these environment differences.

Here are common mistakes beginners make when trying to downgrade CocoaPods.

Mistake 1: Installing an older version and assuming it becomes active automatically

Broken expectation:

gem install cocoapods -v 1.14.3
pod --version
# still shows 1.15.2

Why it happens:

• another installed version is still being used by your shell,
• or your Ruby environment is not the one you think it is.

How to avoid it:

• check installed versions with gem list cocoapods
• use a Gemfile
• run bundle exec pod --version

Mistake 2: Uninstalling everything unnecessarily

Broken approach:

gem uninstall cocoapods

This can remove versions you still need for other projects.

Better approach:

gem uninstall cocoapods -v 1.15.2

Remove only the version you no longer want.

Mistake 3: Confusing CocoaPods version with pod dependencies

Beginners sometimes think this command changes dependency versions:

gem install cocoapods -v 1.14.3

It does not change the versions of libraries in your Podfile. It changes the version of the CocoaPods tool itself.

Mistake 4: Running pod install globally in a project that expects Bundler

Broken pattern:

pod install

Safer pattern:

bundle exec pod install

This ensures the command uses the project's pinned gem versions.

Mistake 5: Ignoring Ruby environment differences

You may install CocoaPods in one Ruby environment and run pod from another.

How to avoid it:

• verify ruby -v
• verify which ruby
• verify which gem
• verify which pod

These checks help confirm you are using the expected toolchain.

Here is how the main approaches compare.

Global install vs project-pinned install

In most professional projects, project-pinned usage is preferred.

# Install a specific CocoaPods version
gem install cocoapods -v 1.14.3

# List installed CocoaPods versions
gem list cocoapods

# Check active pod version
pod --version

# Uninstall one specific version
gem uninstall cocoapods -v 1.15.2

# Gemfile
source "https://rubygems.org"
gem "cocoapods", "1.14.3"

# Install gems from Gemfile
bundle install

# Run the pinned CocoaPods version
bundle exec pod --version
bundle exec pod install

Key rules

• CocoaPods is a Ruby gem.
• -v installs an exact version.
• Multiple versions can be installed at once.
• pod --version shows the active version, not all installed versions.
• Gemfile + bundle exec is the safest project workflow.

Useful checks

which ruby
which gem
which pod
ruby -v
gem -v

How do I install a specific CocoaPods version?

Use:

gem install cocoapods -v 1.14.3

Replace 1.14.3 with the version you need.

How do I downgrade CocoaPods to an older version?

Install the older version first. If needed, uninstall the newer one or use Bundler so your project runs the exact version you want.

Can I have multiple CocoaPods versions installed at the same time?

Yes. RubyGems allows multiple installed versions of the same gem.

Why does pod --version still show the newer version after I install an older one?

Because your shell may still be using a different installed executable or Ruby environment. Use gem list cocoapods and prefer bundle exec pod --version in a project.

What is the safest way to use an older CocoaPods version in a team project?

Create a Gemfile, pin the CocoaPods version there, run bundle install, and use bundle exec pod install.

Does changing the CocoaPods version change the pods in my Podfile?

No. It changes the CocoaPods tool version, not the dependency versions listed in your project.

Should I uninstall the latest CocoaPods version before installing an older one?

Not necessarily. You can keep both installed and use the right one for each project.

• RubyGems — CocoaPods is installed and versioned as a Ruby gem.
• Bundler — Used to pin and run exact gem versions per project.
• PATH environment variable — Affects which pod executable your shell runs.
• Ruby version managers — Tools like rbenv or RVM can change which gems are available.
• Semantic versioning — Helps you understand version numbers like 1.14.3.
• Dependency locking — Related because teams want reproducible builds and tool versions.
• Command-line tools — CocoaPods is a CLI tool, so shell environment matters.
• CI/CD environments — Tool version consistency is important in automated builds.