How to Install CocoaPods on a Mac (and Fix gem Errors)

Why this happens

CocoaPods is not an Xcode plugin or a standalone binary. It is a Ruby gem, so “installing CocoaPods” really means “installing a gem into a Ruby that your shell can find”. Nearly every failed install comes from that indirection rather than from CocoaPods itself.

macOS ships with a Ruby, but it is old and lives in a SIP-protected system directory. That causes two different failures. Without sudo, gem install cocoapods stops with a permission error because your user cannot write into the system gem directory. With sudo, the install may stop on a dependency such as activesupport requires Ruby version >= 2.2.2, because current CocoaPods and its dependencies need a newer Ruby than the one Apple bundles.

The rest of the confusion is outdated instructions. Guides written before CocoaPods 1.8 start with pod setup and a several-hundred-megabyte specs download. That step is gone: specs are now fetched from a CDN on demand, so pod setup is no longer part of a normal install.

How to fix it

1. Install with Homebrew (most reliable)

Homebrew brings its own Ruby and installs outside the system directories, so there is no sudo and no fight with SIP.

brew install cocoapods
pod --version

If pod --version prints a version number, the install is done. Jump to step 4.

2. Install the gem into your user directory

If you prefer not to use Homebrew, install the gem as your own user instead of root:

gem install cocoapods --user-install

Gems land in a per-user directory that is not on your PATH by default, which is why pod then reports command not found. Add it:

export PATH="$(ruby -e 'puts Gem.user_dir')/bin:$PATH"
pod --version

Put that same export line at the end of ~/.zshrc so new terminal windows pick it up.

3. Use a newer Ruby when the system one is too old

If the install stops with ERROR: Error installing cocoapods: activesupport requires Ruby version >= 2.2.2, the Ruby you are installing into is too old. Install a current Ruby with rbenv and install the gem into that:

brew install rbenv ruby-build
rbenv init

Follow the line rbenv init prints to add it to your shell, open a new terminal, then:

rbenv install --list          # pick the latest stable version
rbenv install 3.3.0
rbenv global 3.3.0
gem install cocoapods
pod --version

4. Add pods to an Xcode project

Once pod --version works, the rest is short. Go to the folder that contains your .xcodeproj:

cd ~/Projects/MyApp
pod init
open -a Xcode Podfile

pod init creates a Podfile with your target already listed. Add your dependencies inside the target block:

platform :ios, '17.0'
use_frameworks!

target 'MyApp' do
  pod 'Alamofire', '~> 5.10'
end

Keep use_frameworks! if you are integrating Swift pods. Save, close the Podfile, and install:

pod install

A successful run ends with Pod installation complete! There are X dependencies from the Podfile and X total pods installed. From that point on, close the .xcodeproj and open the .xcworkspace that pod install created. The workspace contains your project plus the Pods project, and building the plain .xcodeproj will fail with missing modules.

5. Match the error message to the fix

• You don't have write permissions for the /usr/bin directory — you ran gem install against the system Ruby without --user-install. Use step 1 or step 2.
• activesupport requires Ruby version >= 2.2.2 — the Ruby is too old. Use step 3.
• xcodeproj's executable "xcodeproj" conflicts with /usr/local/bin/xcodeproj — two installs are fighting over the same binary. Answer n, then remove one of them (brew uninstall cocoapods or gem uninstall cocoapods) and keep a single method.
• pod: command not found right after a successful install — the gem’s bin directory is not on your PATH. Use step 2.
• arch -x86_64 pod install is an old Apple silicon workaround that only helps when something was installed under Rosetta. Reinstalling through Homebrew so every tool matches the native architecture is the cleaner fix.

How to prevent it

• Pick one install method per machine (Homebrew or a user gem) and stick to it; mixed installs cause the xcodeproj conflict warning.
• Never sudo gem install into the system Ruby. It writes outside your control and breaks on the next macOS update.
• Commit Podfile and Podfile.lock, and add Pods/ to .gitignore. The lock file is what keeps a team on identical versions.
• Always reopen the .xcworkspace after pod install, not the .xcodeproj.
• Run pod install for day-to-day work. Reach for pod update <name> only when you actually want a newer version of that pod.
• If a pod version you know exists is reported as not found, refresh the spec index with pod repo update.

FAQ

Do I still need to run pod setup?

No. Since CocoaPods 1.8 the spec repository is served from a CDN and fetched on demand, so pod setup is not part of the install flow. If your local index is stale, use pod repo update instead.

Should I use pod install or pod update?

pod install respects Podfile.lock and only resolves what is missing, so it is the safe default. pod update ignores the lock file for the named pods and moves them to newer versions, which is a deliberate change you should commit on purpose.

Can CocoaPods and Swift Package Manager live in the same project?

Yes. Xcode supports Swift packages alongside a CocoaPods workspace, and many apps migrate one dependency at a time. Keep the Podfile for what has not moved yet and add the rest through File > Add Package Dependencies.