Master CocoaPods: Install, Switch, and Manage Multiple Versions Efficiently

What Is CocoaPods

CocoaPods

is the Swift & Objective‑C dependency manager for the macOS Xcode development environment. It enables iOS and macOS developers to share code libraries easily, greatly boosting activity in the Apple developer community.

Background of CocoaPods Development

The CocoaPods project started in 2011 (version 0.0.1) and gained attention in 2013 (0.26). It is now an essential tool for iOS/macOS development (e.g., 1.6.1). Its rapid rise is attributed to three main reasons:

The Apple developer community matured and needed a code‑distribution tool to increase activity.

Projects shifted from mono‑repo to multi‑repo structures, requiring better dependency management.

Scripting languages and their native package managers (npm, Maven, NuGet, pip, Composer, SPM, etc.) became widespread.

Ruby on Rails slowed down after 2010, and many Ruby developers sought new directions with the rise of mobile development.

CocoaPods Project Components

CocoaPods consists of four main parts:

The CocoaPods tool, which provides commands for using component libraries and generates an integrated Xcode environment.

The Specs repository, storing description files for all open‑source libraries (e.g.,

*.podspec.json

).

The Plugins mechanism (e.g., CocoaPods‑Packager) for extending functionality.

The CocoaPods‑App, which helps create concise

Podfile

files and reduces DSL maintenance cost.

CocoaPods Installation and Uninstallation

1. Normal Install / Uninstall

Install the latest stable version:

<code>[sudo] gem install cocoapods</code>

Install a specific version (e.g., 1.6.1):

<code>[sudo] gem install cocoapods -v 1.6.1</code>

Install a beta version:

<code>[sudo] gem install cocoapods --pre</code>

Uninstalling involves removing CocoaPods itself and its dependent gems. List installed CocoaPods‑related gems:

<code>gem list --local | grep cocoapods</code>

Then uninstall each gem:

<code>[sudo] gem uninstall cocoapods-*</code>

2. Multi‑Version Install, Switch, Uninstall

When multiple projects require different CocoaPods versions, you can manage them locally using one of the following methods (choose only one).

Homebrew Install & Switch

Install the latest version:

<code>brew update
brew info --github cocoapods
brew install cocoapods</code>

Update to a newer version:

<code>brew update
brew upgrade cocoapods</code>

Install a specific version (e.g., 1.5.3):

<code>git -C "$(brew --repo homebrew/core)" fetch --unshallow
git -C "$(brew --repo homebrew/core)" log master -- Formula/cocoapods.rb
# Find the commit for 1.5.3
cd "$(brew --repo homebrew/core)"
git checkout -b cocoapods-1.5.3 <commit‑hash>
HOMEBREW_NO_AUTO_UPDATE=1 brew install cocoapods
git checkout master
git branch -d cocoapods-1.5.3</code>

Switch versions (e.g., from 1.6.1 to 1.5.3):

<code>brew switch cocoapods 1.5.3</code>

Uninstall a specific version:

<code>brew uninstall cocoapods</code>

RVM + Gemset Switch

Create and use a gemset for a specific CocoaPods version:

<code>rvm gemset create pods-1.6.1
rvm gemset use pods-1.6.1
gem install cocoapods -v 1.6.1</code>

Install another version (e.g., 1.5.3) in a separate gemset:

<code>rvm gemset create pods-1.5.3
rvm gemset use pods-1.5.3
gem install cocoapods -v 1.5.3</code>

Switch between versions:

<code>rvm gemset use pods-1.6.1   # switch to 1.6.1
rvm gemset use pods-1.5.3   # switch to 1.5.3
rvm use [email protected] --default   # set Ruby 2.5.3 with pods-1.6.1 as default</code>

Uninstall a version (e.g., 1.6.1):

<code>rvm gemset delete pods-1.6.1</code>

RVM + Bundler + Gemfile Switch (Recommended)

This method locks the CocoaPods version per project using Bundler.

For Project A needing CocoaPods 1.6.1:

<code>bundle init   # creates Gemfile in the Xcode project root</code>

Edit

Gemfile

to specify the version:

<code>source "https://rubygems.org"

gem "cocoapods", "1.6.1"
# add other gem dependencies as needed</code>

Install the gems and generate

Gemfile.lock

:

<code>bundle install</code>

For Project B needing CocoaPods 1.5.3, repeat the same steps with version 1.5.3 in its own

Gemfile

. Each project now uses its locked CocoaPods version without affecting the global environment.

Summary

This section covered:

What CocoaPods is

The history and evolution of CocoaPods

The main components of the CocoaPods ecosystem

How to install, uninstall, and switch between multiple CocoaPods versions

Reference Articles

REPO 风格之争：MONO VS MULTI - 知乎 (https://zhuanlan.zhihu.com/p/31289463)

Using macOS Homebrew to Install a Specific Version | Nick Galbreath (https://www.client9.com/using-macos-homebrew-to-install-a-specific-version/)

homebrew - Brew List and Install Specific Versions of Formula - Stack Overflow (https://stackoverflow.com/questions/53837861/brew-list-and-install-specific-versions-of-formula)

RVM 官方网站 (https://rvm.io/)