How to install CocoaPods on Mac with Homebrew or RubyGems

Introduction

When I first installed CocoaPods on my MacBook, I made it harder than it needed to be.

If you just want CocoaPods working, the shortest path is Homebrew.

For most people, that is really the whole story.

There is another path, though. CocoaPods is a Ruby tool, and the official guide still installs it with gem install cocoapods. If you already manage Ruby with rbenv, that route gives you more control. In this post, I'll walk through both methods, explain when I'd use each one, and point out a couple of mistakes that are easy to make.

Quick answer

If you only need the command, here it is:

brew install cocoapods
pod --version

If pod --version prints a version number, you are good.

If you are setting up a Ruby environment on purpose, skip to the RubyGems section below.

Which install method should you use?

Use Homebrew if:

• you want the fastest setup on a Mac
• you already use Homebrew for developer tools
• you do not care about managing CocoaPods through a specific Ruby version

Use RubyGems with rbenv if:

• you already use rbenv
• you want CocoaPods tied to your Ruby setup instead of a Homebrew formula
• you prefer to avoid the system Ruby that ships with macOS

The official CocoaPods guide recommends using a newer Ruby instead of the system Ruby that ships with macOS. It mentions version managers such as rbenv or rvm, and it also notes that Homebrew can be part of that setup.

Method 1: install CocoaPods on Mac with Homebrew

This is the simplest method, and it's the one I'd suggest to most Mac users.

Step 1: install Homebrew if you do not have it yet

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

If you already have Homebrew, skip this step.

Step 2: install CocoaPods

brew install cocoapods

Step 3: verify the installation

pod --version
which pod

pod --version tells you whether CocoaPods is installed. which pod tells you which binary your shell is actually using.

Step 4: use it in your project

Inside your iOS project directory, you can now run:

pod install

If this is your first time using CocoaPods, the next thing worth reading is the official guide on using CocoaPods, especially the difference between pod install and pod update.

Method 2: install CocoaPods with RubyGems and rbenv

I'd take this route only if you already manage Ruby versions locally, or if you want CocoaPods to live inside your Ruby setup instead of Homebrew.

Step 1: install rbenv

brew install rbenv ruby-build

Then initialize it in your shell:

eval "$(rbenv init - zsh)"

If you use another shell, use the matching rbenv init command for that shell.

Step 2: install a Ruby version

List the installable Ruby versions:

rbenv install -l

Pick a recent stable version from that list, then install it and make it your global default:

rbenv install <ruby-version>
rbenv global <ruby-version>
ruby -v

Example:

rbenv install 3.4.1
rbenv global 3.4.1
ruby -v

Step 3: install CocoaPods with RubyGems

gem install cocoapods

Then verify it:

pod --version
which pod

What about sudo gem install cocoapods?

The official getting started guide says CocoaPods can be installed with the default Ruby on macOS, but it also makes it pretty clear that avoiding the system Ruby is the safer long-term move.

If you install with the system Ruby, you may need:

sudo gem install cocoapods

That can work, but I would still try Homebrew or rbenv first. It is usually cleaner, and it avoids the permission problems that tend to show up later.

Common problems

brew install pod does not work

This mistake is common enough that it is worth calling out directly.

The correct command is:

brew install cocoapods

Not:

brew install pod

pod: command not found

First, check whether CocoaPods was installed:

pod --version
which pod

If Homebrew installed it but your shell still cannot find it, open a new terminal first. If that does not help, make sure your Homebrew bin directory is on PATH.

If you installed with RubyGems, make sure the gem bin path is available in your shell.

Permission errors when running pod commands

The CocoaPods troubleshooting guide notes that root-owned files can cause permission problems later if CocoaPods was run as root in the past.

Their suggested cleanup commands are:

sudo rm -fr ~/Library/Caches/CocoaPods/
sudo rm -fr ~/.cocoapods/repos/master/

If you still hit permission errors inside a project, you may also need to remove the local Pods/ directory and run pod install again.

How do I check whether CocoaPods is installed?

Run:

pod --version
which pod

If both commands work, you are in decent shape.

My recommendation

If you're new to CocoaPods and you're on a Mac, I'd start with Homebrew.

brew install cocoapods
pod --version

If you already use rbenv or you want CocoaPods managed as part of your Ruby setup, install it with gem install cocoapods after switching to your chosen Ruby version.

That is really the whole decision. Use Homebrew if you want the fastest path. Use RubyGems with rbenv if you already care about your Ruby environment. Most of the confusion comes from mixing these two approaches without being clear about why you are using one over the other.

I wish I had understood that earlier. It would have saved me a bunch of time.

References

• CocoaPods getting started guide
• CocoaPods troubleshooting guide
• Homebrew formula for CocoaPods