Troubleshoot & Fix: Unable to Build Gem Native Extension - Comprehensive Guide

In this comprehensive guide, we will walk through the process of troubleshooting and fixing the common error "Unable to build gem native extension" that developers face while working with Ruby gems.

Table of Contents

  1. Introduction
  2. Common Causes
  3. Step-by-Step Solutions
  1. FAQ
  2. Related Links


Ruby gems are essential for developers working with the Ruby programming language. Gems are used to manage and extend the functionality of Ruby applications. However, sometimes developers encounter issues while installing or updating gems, one of which is the "Unable to build gem native extension" error.

Common Causes

The "Unable to build gem native extension" error usually occurs due to one or more of the following reasons:

  1. Missing development tools or libraries required to build native extensions.
  2. Outdated versions of Ruby or RubyGems.
  3. Incompatibility between the gem and the system's installed Ruby version.
  4. Conflicting dependencies.

Step-by-Step Solutions

Installing Development Tools

To compile and install native extensions, you need to have development tools and libraries installed on your system. Here's how to install them on different platforms:

For macOS:

  1. Install Xcode Command Line Tools by running the following command:
xcode-select --install
  1. Install Homebrew by following the instructions on their website. Then, run:
brew install openssl readline

For Ubuntu/Debian:

Run the following command in your terminal:

sudo apt-get install build-essential libssl-dev libreadline-dev zlib1g-dev

For CentOS/RHEL/Fedora:

Run the following command in your terminal:

sudo yum groupinstall "Development Tools"
sudo yum install openssl-devel readline-devel zlib-devel

Updating RubyGems

Ensure that you have the latest version of RubyGems installed. To update RubyGems, run the following command:

gem update --system

Installing Specific Gem Versions

Sometimes, the error occurs due to incompatibility between the gem and the system's installed Ruby version. In such cases, installing a specific version of the gem might resolve the issue. To install a specific version, use the following command:

gem install <gem_name> -v <gem_version>


gem install nokogiri -v 1.10.10

Using Bundler

Bundler is a popular tool for managing Ruby gem dependencies. It ensures that your project uses compatible gem versions and resolves dependency conflicts. If you haven't already, install Bundler by running:

gem install bundler

Next, create a Gemfile in your project directory with the following content:

source ''
gem 'gem_name', 'gem_version'

Replace gem_name and gem_version with the actual gem name and version you want to use. Then, run:

bundle install

Bundler will install the specified gem and its dependencies while resolving any conflicts.


1. What is a native extension in Ruby gems?

Native extensions are C or C++ code compiled and linked with Ruby. They extend Ruby's functionality or improve performance by using lower-level languages.

2. How can I find out which gems have native extensions?

You can check the ext directory in the gem's source code or look for extconf.rb files. If either exists, the gem likely has a native extension.

3. How can I list all installed gems on my system?

Run the gem list command in your terminal to display all the installed gems and their versions.

4. How can I uninstall a specific gem version?

To uninstall a specific gem version, use the following command:

gem uninstall <gem_name> -v <gem_version>

5. How can I update a specific gem to the latest version?

To update a specific gem, run:

gem update <gem_name>
  1. RubyGems Official Website
  2. Bundler Official Website
  3. Ruby Official Website
  4. RubyInstaller for Windows
  5. RVM: Ruby Version Manager

Happy coding!

Great! You’ve successfully signed up.

Welcome back! You've successfully signed in.

You've successfully subscribed to

Success! Check your email for magic link to sign-in.

Success! Your billing info has been updated.

Your billing was not updated.