Error installing cocoapods: Failed to build gem native extension
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)
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:
- Install Homebrew (which will also install the prerequisite Apple command line tools)
- Install a Ruby version manager such as chruby and ruby-install (others include rbenv, asdf, and RVM)
- Configure the Ruby version manager
- Install a specific version of Ruby
- 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.
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.
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
.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:
You should see
/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
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:
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
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.