Setup CocoaPods and Ruby

Last Updated 2025-01-13 UTC+8.

CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. It simplifies the process of integrating third-party libraries into your Xcode project. With CocoaPods, you can easily specify the libraries your project depends on in a file called a Podfile, and CocoaPods will handle downloading, configuring, and integrating these libraries into your project.

CocoaPods helps manage dependencies and their versions, making it easier to keep your project up-to-date with the latest versions of the libraries you use. It also helps in resolving dependencies between different libraries, ensuring that everything works together smoothly.

WARNING

You should take this blog as reference only. Please follow the instructions from the official website instead.

WARNING

CocoaPods will become read-only in 2nd December, 2026. We should migrate to use Swift Package Manager (SPM).

Install CocoaPods

Install Ruby (with rbenv)

CocoaPods is built with Ruby (a programming language). You have to install Ruby to use CocoaPods.

Since CocoaPods does not recommend using the system provided Ruby, use rbenv (a version manager tool for Ruby on Unix-like systems) to install a new Ruby.

First, install Homebrew (if you have not done so):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After that, install rbenv with Homebrew:

brew install rbenv

In ~/.zshrc, add the following to hook rbenv into your shell:

eval "$(rbenv init - --no-rehash zsh)"

Verify that rbenv is correctly installed:

$ rbenv version
3.4.1 (set by /Users/cinnieshe/.rbenv/version)

List the latest stable versions of Ruby:

rbenv install -l

List all installed versions of Ruby (if any):

$ rbenv versions
  system
* 3.4.1 (set by /Users/cinnieshe/.rbenv/version)

Install the latest version of Ruby:

$ rbenv install 3.4.1 # Please replace it with the latest version at the time of your reading.
Installed ruby-3.4.1 to /Users/cinnieshe/.rbenv/versions/3.4.1

In ~/.zshrc, to have rbenv installed ruby takes precedence over any system-installed version (FYI, system ruby has path /usr/bin/ruby), add the following before the line eval "$(rbenv init - --no-rehash zsh)":

export PATH="$HOME/.rbenv/bin:$PATH"

Start using Ruby by the following command, sometimes you may need to restart the Terminal to apply the new settings:

rbenv global 3.4.1

Verify if ruby is successfully installed:

$ ruby -v
ruby 3.4.1 (2024-12-25 revision 48d4efcb85) +PRISM [arm64-darwin24]
$ which ruby
/Users/cinnieshe/.rbenv/shims/ruby

Install CocoaPods (with RubyGems)

Install CocoaPods with RubyGems (a package manager for Ruby):

gem install cocoapods

Verify CocoaPods is installed correctly:

$ pod --version
1.16.2

Change Ruby Version (With rbenv)

Check if the Ruby version you want is already installed:

$ rbenv versions
  system
* 2.7.4 (set by /Users/cinnieshe/.rbenv/version)
  3.4.1

(If the Ruby version you want to use is not yet installed) Install the specific Ruby version:

rbenv install X.X.X # Replace X.X.X with your desired version

To change to a specific version, run:

rbenv global X.X.X # Replace X.X.X with your desired version

Verify currently using Ruby version:

$ ruby -v
ruby 3.4.1 (2024-12-25 revision 48d4efcb85) +PRISM [arm64-darwin24]
$ which ruby
/Users/cinnieshe/.rbenv/shims/ruby

Verify if CocoaPods is functioning correctly:

pod --version

Update CocoaPods

To update CocoaPods you simply install the gem again:

gem install cocoapods

Troubleshoot with CocoaPods with Changed Ruby Version

Sometimes, when trying to change the Ruby to the project's version, you might got error such as:

$ pod --version
// ...
The 'pod' command exists in these Ruby versions:
  3.4.1

You might need to reinstall CocoaPods for the specific version of Ruby, but during the process, the terminal output will let you know what additional dependencies might be required to install CocoaPods with that Ruby version, e.g., the following example required to install activesupport and securerandom gems with a specific version.

Use the required Ruby version of the project, and try installing CocoaPods at that Ruby version again:

$ rbenv global 2.7.4
$ gem install cocoapods
ERROR:  Error installing cocoapods:
	The last version of securerandom (>= 0.3) to support your Ruby & RubyGems was 0.3.2.

Based on the error message, install the specific version of securerandom:

$ gem install securerandom -v 0.3.2
$ gem install cocoapods
ERROR:  Error installing cocoapods:
	The last version of activesupport (>= 5.0, < 8) to support your Ruby & RubyGems was 7.1.5.1.

Based on the error message, install the specific version of activesupport:

$ gem install activesupport -v 7.1.5.1
$ gem install cocoapods
Successfully installed cocoapods-core-1.16.2
Successfully installed cocoapods-1.16.2
Parsing documentation for cocoapods-core-1.16.2
Installing ri documentation for cocoapods-core-1.16.2
Parsing documentation for cocoapods-1.16.2
Installing ri documentation for cocoapods-1.16.2
Done installing documentation for cocoapods-core, cocoapods after 1 seconds
2 gems installed

Upon successful CocoaPods installation, verify if CocoaPods is functioning well with the specific Ruby version:

$ pod --version
1.16.2
$ ruby -v
ruby 2.7.4p191 (2021-07-07 revision a21a3b7d23) [arm64-darwin24]

References

1. CocoaPods. (n.d.). Getting Started. https://guides.cocoapods.org/using/getting-started.html
2. GitHub. (n.d.) rbenv. https://github.com/rbenv/rbenv
3. Homebrew. (n.d.) Homebrew. https://brew.sh/