Update: Since version 1.6.7 includes this PR, it should build out-of-the-box on OS X. If you can, update to that version and skip this guide.

Since I constantly have to build nokogiri for some Gem or another and also always forget how to prevent it from falling over itself, here are my notes. The instructions are for Yosemite and were tested on 10.10.3.

Building older versions

Older versions of Nokogiri need to be told where to find certain system libraries. Use this command as an example (it installs version 1.3.3):

$ gem install nokogiri -v 1.3.3 -- --with-iconv-dir=`xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk/usr --with-xml2-include=`xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk/usr/include/libxml2

Building versions >= 1.6.4

The newer versions got better and worse at the same time. Under certain circumstances, one will not have a /usr/include on Yosemite, but nokogiri stubbornly checks for that. The fix for this is ugly, simply to this before installation:

$ sudo mkdir /usr/include
$ sudo touch /usr/include/iconv.h

😭

Updated instructions for OS X 10.11

Building older versions

Basically the same, just the version number of the OS X has increased. Make sure you have Xcode 7.x as your active Xcode, otherwise compilation will fail.

$ gem install nokogiri -v 1.6.3.1 -- --with-iconv-dir=`xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.11.sdk/usr --with-xml2-include=`xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.11.sdk/usr/include/libxml2

Building versions >= 1.6.4

Allright, this is were the sadness begins, because SIP (System Integrity Protection) prevents us from doing the simple workaround we previously could perform. The solution is building the gem manually from source:

Clone the repo
Checkout the tag of whatever version you want to build (e.g. "v1.6.5")
bundle install to get all dependencies of nokogiri installed
Make sure Xcode 7.x is the active Xcode, otherwise compilation will fail
Apply this patch (this gets rid of the /usr/include dependency in the build process)
rake gem to create the Gem itself
sudo gem install pkg/nokogiri-1.6.5.gem (or whatever version you're currently installing)

😮

Updated instructions for OS X 10.12

Building older versions

Basically the same, just the version number of the OS X has increased. Make sure you have Xcode 8.x as your active Xcode, otherwise compilation will fail.

$ gem install nokogiri -v 1.6.3.1 -- --with-iconv-dir=`xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk/usr --with-xml2-include=`xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk/usr/include/libxml2