System Ruby on macOS 10.15 frequently fails to build native gems required by CocoaPods (for example, ffi), leading to errors like:

ERROR: Failed to build gem native extension
checking for ffi.h... no
You have to install development tools first

The reliable approach is to install your own Ruby and use that to install CocoaPods.

1) Confirm you’re on the system Ruby (not recommended)

ruby -v
which ruby

If the path is /usr/bin/ruby, that’s Apple’s Ruby. Avoid installing CocoaPods with it.

2) Install Xcode Command Line Tools

Native gems need compilers and headers.

xcode-select --install

If you previously installed Xcode/CLT, this may report it’s already installed.

3) Install Homebrew

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

If network access to GitHub is blocked, use a VPN, a miror, or adjust DNS/hosts according to your environment.

Verify:

brew -v

4) Install a separate Ruby with rbenv

Using rbenv keeps your Ruby isolated from the system.

brew update
brew install rbenv ruby-build

Initialize rbenv for your shell:

• For zsh (default on Catalina):

echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc

• For bash:

echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
source ~/.bash_profile

Install and activate a Ruby version (choose one CocoaPods supports, e.g., 2.6.5 to mirror older setups on 10.15):

rbenv install 2.6.5
rbenv global 2.6.5
ruby -v
which ruby  # should point to ~/.rbenv/shims/ruby

5) Configure gem sources (optional)

Using the default RubyGems source usually works:

gem sources -l

If you need a mirror (e.g., for regional connectivity), you can add one and remove the default:

gem sources --add https://gems.ruby-china.com/
gem sources --remove https://rubygems.org/
gem sources -l

6) Install CocoaPods with your user-managed Ruby

Do not use sudo when installing into your rbenv Ruby.

gem update --system
gem install cocoapods

Verify the installation:

pod --version
which pod  # should resolve via rbenv shims

Notes and troubleshooting

• If you still see “Failed to build gem native extension” or missing headers (ffi.h, etc.), ensure:
  • Xcode Command Line Tools are installed: xcode-select --install
  • You are using the rbenv Ruby: which ruby should point to ~/.rbenv/shims/ruby
• If pod resolves to a system path, you're shell may not be loading rbenv. Re-check the eval "$(rbenv init ...)" line in your shell startup file and restart the terminal.
• Avoid mixing sudo gem install with a user-managed Ruby. If you used sudo previously, remove any system-installed CocoaPods (sudo gem uninstall cocoapods) and rienstall via rbenv.
• If Homebrew installation fails due to curl errors reaching GitHub, use a reliable network or a mirror for Homebrew and Ruby downloads.