Error installing cocoapods: Failed to build gem native extension

Published by Moncef Belyamani - Updated

Have you been trying to install cocoapods on your Mac and getting this error?

Building native extensions. This could take a while...
ERROR: Error installing cocoapods:
ERROR: Failed to build gem native extension.

This is a common issue people face when trying to install gems on a Mac that doesn’t have a proper Ruby development environment. To make things worse, the cocoapods documentation recommends using the default Ruby that comes with macOS, and to use sudo gem install cocoapods.

You should never use sudo to install gems.

Using the default Ruby is also not recommended because it’s an older version, and you can’t upgrade it. For example, Monterey (Apple’s latest macOS) comes with Ruby 2.6.8. But this version of Ruby reached end of life in March 2022.

So what’s the correct way to install gems on a Mac?

I’m glad you asked! You need to install a separate and newer version of Ruby that you control. There are two ways to do that:

1) Install the new version with a Ruby version manager (recommended)

or

2) Install the new version with Homebrew (not recommended)

I highly recommend using a Ruby manager because it allows you to have multiple versions of Ruby installed at the same time, and makes it easy to switch between them. Even if you’re using Ruby for the first time, it’s worth your time to learn how to use a Ruby manager because you will inevitably need one.

Install Ruby with a version manager

At a high level, there are a minimum of five steps to a working Ruby environment on macOS with a Ruby manager:

  1. Install Homebrew (which will also install the prerequisite Apple command line tools)
  2. Install a Ruby version manager such as chruby and ruby-install (others include rbenv, asdf, and RVM)
  3. Configure the Ruby version manager
  4. Install a specific version of Ruby
  5. Switch to that version of Ruby

You have two options for performing those steps:

  • Have everything set up for you in minutes with a single command
  • Spend an hour or more setting everything up manually

Have everything set up for you in minutes with a single command

Ruby on Mac will automatically install Ruby with chruby, ruby-install, and all the other development tools you’ll need for Rails or Jekyll. It will save you so much time and frustration.

It doesn’t just have a one-time use. You can run it over and over by simply typing “rom” to keep your system up to date and secure. And the next time you get a new Mac, the Ultimate version will save you an entire day because it can also automatically install all your Mac apps, fonts, macOS preferences, and GitHub repos, in addition to a complete development environment. You get all of these time savings now and in the future for a one-time cost.

When you buy Ruby on Mac today, you’ll be supporting an independent developer, and if you need it for your job or business, you should be able to expense it.

Read what people say about Ruby on Mac.

Spend an hour or more setting everything up manually

If you haven’t yet tried to install Ruby or other development tools on your Mac, you should be able to get up and running with the basics by following my free step-by-step guide for installing Ruby on a Mac.

This is the manual equivalent of the “Basic” version of Ruby on Mac, minus the comprehensive troubleshooting guide. You’ll then need to manually install gems, and any other necessary dev tools.

Install Ruby with Homebrew

While this option works, I do not recommend it because you can’t easily switch between different Ruby versions. This is going to cause you major confusion and headaches.

But because I’m thorough, I’ll include it so you can see how it works.

Step 1: Install Homebrew

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

Step 2: Install a Ruby version

Visit the Homebrew site for all the supported Ruby versions you can install. To install the latest:

brew install ruby

Step 3: Update the PATH environment variable to point to Homebrew’s Ruby installation.

echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc

Replace .zshrc with .bash_profile if you’re using bash. If you’re not sure, read my guide to find out which shell you’re using.

Also, note that the location of Homebrew’s installation might be different on M1 Macs. Read the instructions that Homebrew printed to your terminal.

Step 4: Relaunch your Terminal (or open a new tab)

To verify that you are using the Homebrew version of Ruby, run this command:

which ruby

You should see /usr/local/opt/ruby/bin/ruby, or /opt/homebrew/opt/ruby/bin on M1 Macs.

If you don’t, the two most likely reasons are that you didn’t relaunch the Terminal, or the PATH is not set properly. See step 3 above. A misconfigured PATH is a common source of confusion and errors. Instructions for setting the PATH are abundant on the internet, but very few explain what PATH does and why it needs to be updated. Read my guide about PATH to learn more.

Now you should be able to install gems. For example:

gem install jekyll

But wait! What happens if you try to use Jekyll? If you try jekyll -v for example, you’ll get this error:

zsh: command not found: jekyll

What do you mean not found? I can see it when I run gem list! In some cases, this could be due to not relaunching the Terminal (or opening a new tab). In this case though, it’s because Homebrew installs gems in a particular directory that needs to be added to the PATH.

If you paid attention when you ran brew install ruby, you might have noticed a message like this:

By default, binaries installed by gem will be placed into:
  /usr/local/lib/ruby/gems/3.1.0/bin

You may want to add this to your PATH.

In general, Homebrew’s messages are worth reading and very helpful. This one could be clearer and more explicit.

To wrap up this section, in order to be able to install gems and use them with a Homebrew Ruby installation, your PATH needs to include the location of the Homebrew Ruby, as well as the gems location:

export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.1.0/bin:$PATH"

The 3.1.0 above assumes Homebrew installed a Ruby version that starts with 3.1. If you’re using a different version (which you can check with ruby -v), replace 3.1 with the first two digits of your Ruby version.

The downside to installing Ruby with Homebrew is that you can only use one version of Ruby at a time. And you’re also limited to specific versions available on Homebrew. Once you start working on multiple projects, each with its own supported version of Ruby, this quickly becomes unsustainable.