Common Pitfalls When Installing Ruby on Rails

Encountered issues during Ruby on Rails installation. Slowly collecting and sharing them.

Error: Failed to build gem native extension

ERROR: Failed to build gem native extension. /usr/bin/ruby extconf.rb mkmf.rb can't find 
header files for ruby at /usr/share/include/ruby.h

Solution:

  • On CentOS: yum install ruby-devel
  • On Ubuntu: apt-get install ruby-dev

Error: Installing nokogiri fails

ERROR:  Error installing nokogiri:
    ERROR: Failed to build gem native extension.
    ...
    libxml2 is missing.  please visit http://nokogiri.org/tutorials/installing_nokogiri.html for help with installing dependencies.
    *** extconf.rb failed ***

Solution:

sudo apt-get install libxslt-dev libxml2-dev
sudo apt-get install zlib1g-dev   # Install dependency libraries for third-party packages

Speed up gem installation

If intsalling third-party packages feels slow, switch the gem source:

gem source -r https://rubygems.org/ 
gem source -a https://gems.ruby-china.com/

Verify the change with:

gem sources -l

Complete installtaion checklist

sudo apt-get install ruby
sudo apt-get install ruby-dev
sudo apt install ruby-bundler
sudo apt-get install libxslt-dev libxml2-dev
sudo apt-get install zlib1g-dev   # Install dependency libraries for third-party packages
sudo apt-get install libsqlite3-dev
sudo gem install nokogiri
sudo gem install rails
sudo gem install bundler

Tags: ruby Rails installation troubleshooting

Posted on Wed, 12 Aug 2026 16:56:39 +0000 by baccarak