Installing Nokogiri on Mac OS X. This is particularly troublesome with Mavericks but might be useful for later versions.

Nokogiri, the de facto standard XML parser in Ruby-land is often included in a Rails project as a dependency of Capybara.


  • Prior to v1.6.0, Nokogiri required that the XML library (libxml2) and XSLT (libxslt) be manually installed (typically through MacPorts or Homebrew).
    • Note that as of 2014-06-03, the latest brew formula libxml2 installs version 2.9.1. During gem install nokogiri indicates that "libxml2-2.9.0 and higher are currently known to be brokn and thus unsupported by nokogiri, due to compatibility problems and XPath optimization bugs."
  • Starting at v1.6.0, the two libraries are bundled in the gem, itself.
  • However, Nokogiri does NOT bundle the Unicode conversion library (libiconv). Nor is there a brew formula for this library.


While attempting to install Nokogiri, the gem install fails:

$ bundle install
Building nokogiri using packaged libraries.

Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

    /Users/jtigger/.rbenv/versions/2.1.2/bin/ruby extconf.rb 
Building nokogiri using packaged libraries.
libiconv is missing.  please visit for help with installing dependencies.
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers.  Check the mkmf.log file for more details.  You may
need configuration options.

Provided configuration options:

extconf failed, exit code 1

Gem files will remain installed in /Users/jtigger/.rbenv/versions/2.1.2/lib/ruby/gems/2.1.0/gems/nokogiri- for inspection.
Results logged to /Users/jtigger/.rbenv/versions/2.1.2/lib/ruby/gems/2.1.0/extensions/x86_64-darwin-13/2.1.0-static/nokogiri-
An error occurred while installing nokogiri (, and Bundler cannot continue.
Make sure that `gem install nokogiri -v ''` succeeds before bundling.


If you follow the instructions on the Nokogiri project page, you might think you need to install libxml2 and libxslt libraries. YOU DON'T. These libraries are bundled with the project and you only need to install libiconv.

The solution is to:

  1. install the libiconv library (which is missing in Mavericks);
  2. point the gem installer to use that library while building native extensions for nokogiri.

Installing libiconv through brew

First, tap into the formula for libraries that are normally included with Mac OS X:

$ brew tap homebrew/dupes
$ brew install libiconv

Note the path provided for the "prefix" parameter of the ./configure command.

For example:

==> ./configure --prefix=/usr/local/Cellar/libiconv/1.14 --enable-extra-encodings

Installing nokogiri with your libiconv

Now, install nokogiri pointing it to the libiconv you just installed (by specifying the path you noted above).

gem install nokogiri -- --with-iconv-include=/usr/local/Cellar/libiconv/1.14/include \


(last updated: 2014-08-08)

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License