Fix: can’t find gem cocoapods Error on macOS

Why this happens

When you run pod install in an Xcode project directory and see can't find gem cocoapods (>= 0.a) (Gem::GemNotFoundException) from /usr/local/bin/pod, your shell is executing a leftover RubyGems wrapper script. That wrapper expects to find the cocoapods gem inside a specific Ruby installation—such as macOS system Ruby under /Library/Ruby/—but the gem files are no longer there.

This mismatch usually occurs for one of three reasons:

• A macOS system update: System updates can reset or relocate files in /Library/Ruby/, removing previously installed gems while leaving the /usr/local/bin/pod stub behind.
• Switching Ruby managers or Homebrew: If you installed CocoaPods with gem and later switched to Homebrew, rbenv, rvm, or asdf, your active pod binary may still point to the old Ruby path.
• An incomplete uninstall or upgrade: Removing a gem or interrupting an update can leave orphaned executables in /usr/local/bin.

How to fix it

1. Reinstall CocoaPods with Homebrew (Recommended)

Homebrew bundles its own Ruby runtime for CocoaPods, which keeps it isolated from macOS system Ruby and prevents system updates from breaking your setup.

1. Open Terminal and run:

brew reinstall cocoapods

2. If you previously installed CocoaPods with gem, Homebrew may fail during the linking step with an error like:

Error: The `brew link` step did not complete successfully
The formula built, but is not symlinked into /usr/local
Could not symlink bin/pod
Target /usr/local/bin/pod
already exists.

3. Preview the conflicting files before overwriting them:

brew link --overwrite --dry-run cocoapods

4. If the list only shows stale CocoaPods stubs such as /usr/local/bin/pod and /usr/local/bin/xcodeproj, overwrite them with Homebrew’s symlinks:

brew link --overwrite cocoapods

5. Refresh your shell’s command cache and verify the installation:

hash -r
which pod
pod --version

You should now be able to navigate to your Xcode project folder and run pod install.

2. Reinstall CocoaPods via RubyGems

If you prefer managing CocoaPods with RubyGems—or your project relies on a Ruby version manager like rbenv or rvm—uninstall the broken gem reference and reinstall it cleanly.

1. Remove any existing cocoapods gem entries:

sudo gem uninstall cocoapods

2. Reinstall CocoaPods into /usr/local/bin, which avoids macOS System Integrity Protection restrictions on /usr/bin:

sudo gem install -n /usr/local/bin cocoapods

3. If sudo gem install fails with Gem::CommandLineError or you are using a user-owned Ruby installation (rbenv or rvm), omit sudo:

gem install -n /usr/local/bin cocoapods

If you are using rbenv or rvm, you can also run gem install cocoapods without the -n flag so the binary installs into your active Ruby manager’s shims directory.

4. Run pod install inside your project directory.

3. Check for multiple pod binaries on your PATH

Even after reinstalling CocoaPods, an older /usr/local/bin/pod stub can shadow a working installation in /opt/homebrew/bin/pod (on Apple Silicon Macs) or in your Ruby manager’s shim folder.

1. List every pod executable your shell can see, in priority order:

which -a pod

2. Check which Ruby environment is currently active:

which ruby
gem env

3. If the first path returned by which -a pod is an old stub you no longer use, remove it or adjust your PATH in ~/.zshrc so that Homebrew or your Ruby manager appears before /usr/local/bin.

4. Open a new Terminal tab (or run hash -r) and test pod --version.

4. Use Bundler for project-specific CocoaPods versions

If you work on an iOS or macOS team where different repositories require different CocoaPods versions, using Bundler avoids relying on a single global pod binary.

1. Add a Gemfile to the root of your Xcode project:

source "https://rubygems.org"

gem "cocoapods"

2. Install the gem locally and run CocoaPods through Bundler:

bundle install
bundle exec pod install

Using bundle exec ensures RubyGems resolves cocoapods from the project’s Gemfile.lock rather than an arbitrary global stub.

How to prevent it

• Stick to one installation method: Choose either Homebrew (brew install cocoapods) or a Ruby version manager with Bundler, and avoid mixing sudo gem install with brew.
• Avoid installing gems into macOS system Ruby: System Ruby under /Library/Ruby/ is not meant for third-party development tools and can break after OS updates.
• Pin CocoaPods in a Gemfile: Running bundle exec pod install keeps teammates and CI machines on the exact same CocoaPods version.
• Check which -a pod after OS or Homebrew upgrades: Catching shadowed binaries early saves time when pod install suddenly fails.

FAQ

Why does pod install look in /Library/Ruby/Site after a macOS update?

The /usr/local/bin/pod stub was created when CocoaPods was installed against macOS system Ruby. When a macOS update modifies or clears system Ruby gem directories, the stub remains in /usr/local/bin and fails with Gem::GemNotFoundException because the underlying gem is gone.

Should I install CocoaPods with Homebrew or gem install?

For most solo developers, Homebrew (brew install cocoapods) is simpler because it manages its own Ruby dependency separately from macOS. If your team pins a specific CocoaPods version across projects, use a Ruby version manager (rbenv or rvm) paired with a Gemfile and bundle exec pod install.

How do I fix Could not symlink bin/pod when running brew link cocoapods?

This error means an older pod (and often xcodeproj) file already exists at /usr/local/bin/pod from a previous RubyGems install. Run brew link --overwrite --dry-run cocoapods to confirm only those stale stubs are affected, then run brew link --overwrite cocoapods to replace them.