Error installing puma: Failed to build gem native extension

Published by Moncef Belyamani

Have you been trying to install the Puma gem on your Mac and getting this error?

Building native extensions. This could take a while...
ERROR: Error installing puma:
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. This particular error can also be due to missing or broken command line tools.

So how can we fix this?

While there are various ways to install gems on a Mac, there’s really only one method that should be recommended: using a version manager. If you’re really curious about the other ways, read my definitive guide to installing gems on a Mac.

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.

Over the past ten years, I’ve helped thousands of people set up Ruby on their Mac. It’s my specialty. From clean Macs, to OpenSSL errors, to the most obscure issues, I’ve seen and fixed it all. And the most reliable solution is to use a version manager, specifically chruby.

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.

With Ruby on Mac Prime, you can also choose to automatically install other essential development tools. And if you’ve already tried to install Puma using another method, and you’re running into issues, Ruby on Mac Prime will fix those as well!