How to Install CocoaPods on macOS the Right Way and Fix “pod: command not found”

The pain point: most CocoaPods install guides are only two lines long. That is exactly why so many people end up with pod: command not found, broken Ruby paths, or a Flutter/iOS build that fails at the dependency step.

What CocoaPods is actually doing

CocoaPods is still the dependency manager sitting in the middle of a lot of iOS projects, including many Flutter apps that include iOS plugins. When pod install fails, the error looks small, but the damage is real: your iOS workspace cannot resolve native dependencies, the generated .xcworkspace never becomes trustworthy, and you start wasting time on Xcode errors that are really environment errors.

The clean way to install it on macOS is not to throw random commands at the shell until one works. You want to confirm four layers in order:

1. Xcode command line tools
2. a working Ruby and gem
3. CocoaPods installation
4. PATH and shell visibility

Step 1: install Xcode command line tools

Run this first:

xcode-select --install

If macOS says the tools are already installed, verify the active developer directory:

xcode-select -p

If the path looks wrong after an Xcode update, reset it:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Then accept the Xcode license if needed:

sudo xcodebuild -license accept

Step 2: check Ruby and gem before touching CocoaPods

macOS ships with Ruby, but the real issue is usually not “is Ruby installed?” The issue is whether the shell can find the right gem binary and whether the install path ends up on your PATH.

Check the basics:

ruby -v
which ruby
gem -v
which gem

If those commands fail, do not skip ahead to CocoaPods. Fix Ruby first.

Step 3: install CocoaPods

The official CocoaPods setup path is still RubyGems:

sudo gem install cocoapods

On some machines, especially where you prefer a user-level gem location instead of touching the system area, you may choose a non-sudo Ruby setup. But if your goal is to get a normal Mac development machine unblocked quickly, the command above is the most direct official route.

After installation, initialize CocoaPods once:

pod setup

Then verify it:

pod --version

Step 4: if pod is still not found, the problem is usually PATH

This is the trap that frustrates people. gem install cocoapods may succeed, but pod is still invisible to your shell.

Inspect gem paths:

gem env
gem environment

Pay attention to the executable directory. Then inspect your shell PATH:

echo $PATH

If the gem executable directory is missing, add it to your shell config. For zsh, that is usually ~/.zshrc.

Example:

echo 'export PATH="$HOME/.gem/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

If you installed Ruby in a different location, the correct bin path may differ. That is why checking gem env first matters.

Step 5: run CocoaPods inside your iOS project correctly

Once the environment is healthy, move into the iOS project directory and install dependencies:

cd ios
pod install

If you want CocoaPods to refresh specs before retrying:

pod repo update
pod install

If the lockfile and Pods directory are clearly stale and you want a cleaner retry:

rm -rf Pods Podfile.lock
pod install

Common failure patterns and what they really mean

pod: command not found

Usually one of these:

• CocoaPods did not install
• it installed but into a bin directory not on PATH
• the shell session was not reloaded

xcode-select: error

Usually:

• command line tools are missing
• Xcode moved after an update
• the active developer directory points to the wrong place

Flutter iOS build fails before native plugins resolve

Usually:

• CocoaPods is not installed
• CocoaPods exists but flutter cannot see it
• the ios/Podfile.lock and generated Pods state are stale

For Flutter specifically, this sequence is often enough after fixing CocoaPods:

flutter clean
flutter pub get
cd ios
pod install
cd ..
flutter run

The calm way to debug this on a real Mac

If you are stuck, do not keep re-running pod install blindly. Check the chain in order:

xcode-select -p
ruby -v
gem -v
which pod
pod --version

That five-command checklist usually exposes the real break.

Final recommendation

If you are setting up a fresh Mac for iOS or Flutter work, do not stop after “CocoaPods installed.” Make sure pod --version works from a new terminal tab, then run a real pod install in a project. That extra minute is what separates a clean environment from the kind of half-working setup that burns an afternoon later.

Sources

• CocoaPods Guides
• Flutter iOS setup docs