Nokogiri: the Ruby XML and HTML gem that wraps libxml2, libgumbo and xerces and leaves their differences visible

Three parsers sit underneath, and Nokogiri deliberately does not smooth over their differences

Nokogiri relies on native parsers: libxml2, libgumbo and xerces. Its second guiding principle is to be a thin-as-reasonable layer on top of the underlying parsers and not to attempt to fix behavioral differences between them. The first is to be secure by default, treating all documents as untrusted.

The consequence is that behaviour depends on which parser handles your document. HTML4, HTML5 and XML go through different engines, and the same markup can produce a different tree depending on that choice. The library will not paper over this for you, so when a result surprises you, ask which parser produced it before looking for a bug in your own query. The untrusted-by-default stance means you do not have to opt into protective settings when parsing input from outside.

Parser coverage is uneven: SAX and push parsing stop at HTML4

The feature list is DOM parsing for XML, HTML4 and HTML5, a SAX parser for XML and HTML4, and a push parser for XML and HTML4. Search is available through XPath 1.0 and CSS3 selectors with some jquery-like extensions. It also offers XSD schema validation, XSLT transformation, and a Builder DSL for XML and HTML documents.

The gaps are worth noting. HTML5 appears only in the DOM line, so a streaming SAX or push approach to HTML5 is not offered. XPath is version 1.0, which means no XPath 2.0 functions. If you process very large XML files without holding the whole tree, use the SAX or push parser, and accept that you give up the convenient search methods that work on a full DOM.

Native gems install in seconds, but only on the listed platforms

Native gems contain pre-compiled libraries for a specific machine architecture. On supported platforms they remove the need to compile the C extension and the packaged libraries, and the README says this makes installation much faster and more reliable. The list covers Linux with x86_64, aarch64 and arm on glibc, which requires glibc 2.29 or newer, the same three on musl, macOS on x86_64 and arm64, Windows x64-mingw-ucrt, and any platform running JRuby 10.0 or newer.

To check whether your machine matches, run one of these:

bundle platform
ruby -e 'puts Gem::Platform.local.to_s'

If you match, gem install or bundle install fetches a native gem with no extra action. A system with an older glibc, or a platform not on the list, falls through to compiling, which is the slow and fragile path.

Compiling from source needs a C toolchain, Ruby headers and libxml2 2.9.2 or newer

Because Nokogiri is a C extension, installing it without a native gem requires a C compiler toolchain, the Ruby development header files and some system dependencies. The simple command the README offers for that case is:

gem install nokogiri

It carries the qualifier that it may work if you have an appropriately configured system. For problems, the project points to its Installing Nokogiri tutorial and has an Installation Difficulties issue template. If you compile against a system libxml2, the minimum is 2.9.2 and the recommended version is 2.12.0 or newer. So a distribution that ships an old libxml2 can build, but you are below the version the project recommends, and security fixes in the library would then depend on your operating system.

Requirements are Ruby 3.2 or JRuby 10.0, and minor releases may drop EOL Rubies

The stated requirements are Ruby 3.2 or newer and JRuby 10.0 or newer. The semantic versioning policy explains how that can change. A major bump is reserved for significant backward-incompatible public API changes that would require rewriting application code, and the README says the project has never done it. Minor releases cover features, bugfixes, updating packaged libraries for non-security reasons, dropping support for EOL Ruby versions, internal or private changes, and removing deprecated methods after a transition period. Patch releases are bugfixes, security updates and updates of packaged libraries for security reasons.

The practical rule: a minor upgrade can break an app that sits on an end-of-life Ruby, and it can remove a deprecated method you still call. The project acknowledges some people object to dropping Ruby versions in minors. Read each changelog entry's Changes section before moving.

Three patch releases landed on the same day, 2026-11-02

The recent releases are v1.19.7 at 18:23 UTC, v1.19.6 at 07:03 UTC and v1.19.5 at 03:44 UTC, all on 2026-11-02. The last push was on 2026-11-01 and the repository is not archived. Under the versioning policy, patch releases carry bugfixes, security updates and security-related library updates.

Three patch versions in a day is unusual, so read the changelog for 1.19.5 through 1.19.7 before pinning one. If you run in production, pin the exact patch version in your Gemfile and upgrade deliberately. Security issues are reported through the repository's security page, and SECURITY.md describes the policy.

Help channels are split by purpose, and the project asks you not to email maintainers

Official documentation lives at nokogiri.org, and its source repository accepts contributions. The reading list is the API documentation, the tutorials and a community-maintained cheat sheet on the wiki. Exploratory questions go to the nokogiri-talk mailing list, a Help Request issue, or a discussion. Bugs go through the Bug Report or Installation Difficulties templates, and vulnerabilities go to the security page. The README asks you not to mail the maintainers at personal addresses.

The repository also includes ROADMAP.md, an adr directory of architecture decision records, LICENSE-DEPENDENCIES.md and a patches directory, along with the bundled gumbo-parser. Funding is through GitHub Sponsors, Open Collective and Tidelift.

Editorial conclusion

Nokogiri is the default choice for a Ruby application that parses, queries or builds XML and HTML, especially when installation speed matters and a precompiled gem exists for your platform. It is the wrong choice on Ruby older than 3.2, on a platform outside its native gem list unless you can compile, or when you expect it to hide differences between HTML4 and HTML5 parsers. Before upgrading, read the changelog, since minor releases may drop EOL Ruby versions and remove deprecated methods.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. sparklemotion/nokogiri on GitHub