# Nokogiri for Ruby: parsing HTML and XML with libxml2, libgumbo and xerces

> Nokogiri is the long-standing Ruby gem for reading, querying and rewriting HTML and XML. It is a thin layer over native parsers, which is where both its speed and its sharp edges come from.

**sparklemotion/nokogiri** — Nokogiri (鋸) makes it easy and painless to work with XML and HTML from Ruby.

- Repository: https://github.com/sparklemotion/nokogiri
- Website: https://nokogiri.org/
- Stars: 6,282 · Forks: 951
- Language: C
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/sparklemotion-nokogiri

## The problem Nokogiri solves for Ruby programs that touch markup

Ruby's standard library ships REXML, a pure-Ruby XML parser. It works, and it is slow, and it has no HTML story worth the name. Anyone scraping a page, reading a vendor's SOAP response, or rewriting a config document ends up needing a parser that tolerates malformed HTML, understands namespaces, and can be pointed at a node with a selector. Nokogiri is that parser. The README describes it as making it "easy and painless to work with XML and HTML from Ruby", and the feature list is the real specification: DOM parsers for XML, HTML4 and HTML5, SAX and push parsers for XML and HTML4, XPath 1.0 search, CSS3 selectors with jquery-like extensions, XSD schema validation, XSLT transformation, and a Builder DSL for producing documents. The audience is Ruby developers who already have markup to deal with, not people choosing a data format. If your payload is JSON, Nokogiri has nothing to offer you.

## A thin layer over libxml2, libgumbo and xerces, and what that costs you

Nokogiri does not implement a parser. It binds to native ones: libxml2 for XML and HTML4, libgumbo for HTML5, and xerces on JRuby. Two guiding principles in the README explain the consequences. The first is to be secure-by-default by treating all documents as untrusted. The second is to be a "thin-as-reasonable layer" on top of the underlying parsers and not to fix behavioral differences between them. That second principle is the one to sit with. It means an HTML5 document parsed through libgumbo and an HTML4 document parsed through libxml2 can disagree, and Nokogiri will not normalize the disagreement away. The gem exposes the parsers rather than hiding them, and the choice of parser is part of your program's behavior, not an implementation detail. The benefit is that you get the mature C libraries' speed and their accumulated handling of broken real-world markup. The cost is that you inherit their quirks, their version differences, and their security history, which is why the project ships a SECURITY.md and a dedicated vulnerability reporting channel at github.com/sparklemotion/nokogiri/security.

## Installing Nokogiri and parsing your first document

The README states the requirements plainly: Ruby >= 3.2, or JRuby >= 10.0. If you compile the native extension against a system libxml2 you need libxml2 >= 2.9.2, with >= 2.12.0 recommended. The preferred path avoids compilation entirely. Nokogiri publishes pre-compiled native gems for a listed set of platforms, which the README says removes the need to compile the C extension and the packaged libraries or to have system dependencies present, and calls out faster and more reliable installation as the result. Before installing, check whether your machine is on that list. The README suggests running bundle platform to determine whether your system supports one of these gems.

```bash
bundle platform
```

Compare the output against the supported list: x86_64-linux-gnu, aarch64-linux-gnu and arm-linux-gnu (glibc >= 2.29), the musl equivalents, x86_64-darwin and arm64-darwin, x64-mingw-ucrt, and any platform running JRuby 10.0 or higher. If your platform matches, installation is a normal gem install or bundle install and no compiler runs. The README points to nokogiri.org for the API documentation and tutorials on parsing, modifying and searching documents, so the exact call for your first document is documented there rather than in the README itself.

## Where Nokogiri is the wrong tool

The behavioral-difference principle cuts both ways. If your pipeline depends on identical tree output regardless of which parser handled the input, Nokogiri's stated refusal to reconcile libxml2 and libgumbo means you own that reconciliation. The README does not document any normalization layer, and it does not document rollback or a compatibility mode either, so do not assume one exists. A second boundary is XPath. The feature list says XPath 1.0, so XPath 2.0 features such as sequences, FLWOR expressions or the richer function library are simply not available through this API; if you need them you are looking at a different runtime, not a Nokogiri option. A third is scope. Nokogiri parses and queries markup. It is not a sanitizer, not an HTTP client, and not a schema language. The README lists XSD validation but nothing about HTML sanitization, so passing untrusted markup through it and rendering the result is a decision you make outside the gem. Finally, the version policy has teeth: the README says dropping support for end-of-life Ruby versions is a minor-version change, and links to an issue where people objected. A minor bump can therefore end your upgrade path if you are pinned to an old Ruby.

## Nokogiri versus REXML, and the alternative search

The obvious alternative inside Ruby is REXML, which ships with the standard library and needs no native extension and no compiler. The difference is architectural rather than cosmetic. REXML is a pure-Ruby XML parser, so it is portable to anything that runs Ruby and it carries no C dependency to audit. Nokogiri is a binding to libxml2, libgumbo and xerces, which is why it can offer HTML5 parsing, CSS3 selectors, XSD validation and XSLT in one place while REXML offers an XML parser. If your input is well-formed XML, your documents are small, and you value having zero native code in your dependency tree, REXML is a defensible choice. If you are parsing HTML that came off the web, or you want to select nodes with CSS, or you need XSLT, Nokogiri is the one with the feature list. The trade is that you accept a compiled dependency, a platform matrix, and the parsers' own release cycles. There is no free option here; you are choosing which set of problems you would rather debug.

## Maintenance, versioning and what the MIT licence does not cover

The repository is not archived, and the last push was on 2026-09-21. Releases are regular: v1.19.4 on 2026-06-18, v1.19.3 on 2026-04-27, v1.19.2 on 2026-03-19. The project follows Semantic Versioning and states that it has never bumped the major version. Minor releases carry features, bugfixes, updates to packaged libraries for non-security reasons, removal of deprecated methods after a transition period, and the Ruby EOL drops mentioned above. Patch releases carry bugfixes, security updates, and packaged-library updates made for security reasons. That last line is the upgrade cost in practice: security fixes to libxml2 or libgumbo arrive as a new gem version, so staying current is how you get them. The gem itself is MIT licensed, but the native libraries it binds to are separate works with their own terms, and the repository carries a LICENSE-DEPENDENCIES.md file for exactly that reason. Read it before you ship; this is a description of the repository layout, not legal advice.

## Conclusion

Adopt Nokogiri if you work with HTML or XML in Ruby and want XPath 1.0, CSS3 selectors, SAX, XSLT and schema validation behind one API. Do not adopt it if your documents are JSON, if you need XPath 2.0 or later, or if you expect the gem to paper over differences between libxml2 and libgumbo, because the README says it deliberately does not. Before you commit, check your platform against the native gem list with bundle platform, and read the SECURITY.md policy if you feed it untrusted input.

## FAQ

### What is the Nokogiri gem used for in Ruby?

It reads, writes, modifies and queries XML and HTML documents from Ruby. The README lists DOM and SAX parsers, XPath 1.0 search, CSS3 selectors with jquery-like extensions, XSD validation, XSLT transformation and a Builder DSL.

### How do I install Nokogiri?

Install the gem normally with gem install or bundle install. On a supported platform this pulls a pre-compiled native gem, which the README says avoids compiling the C extension and avoids needing system dependencies. Requirements are Ruby >= 3.2 or JRuby >= 10.0.

### How do I use Nokogiri to parse a document?

Require the gem and pass your markup to a parser such as Nokogiri::HTML4, which returns a document object you can search with CSS selectors or XPath. The tutorials linked from nokogiri.org cover parsing, modifying and searching documents in detail.

### What is the Nokogiri gem?

It is a Ruby library that provides an API over native parsers: libxml2 and libgumbo, plus xerces on JRuby. The README describes it as a thin-as-reasonable layer that treats all documents as untrusted by default.

### How does Nokogiri compare with REXML?

REXML is a pure-Ruby XML parser in the standard library with no native extension. Nokogiri binds to libxml2, libgumbo and xerces, which is what lets it offer HTML5 parsing, CSS3 selectors, XSD validation and XSLT alongside XML parsing.

### What are alternatives to Nokogiri for Ruby?

REXML is the main in-language alternative and needs no compiled dependency, but it is an XML parser rather than a full HTML and XML toolkit. Which one fits depends on whether you need HTML5 parsing, CSS selectors or XSLT, all of which the Nokogiri README lists as features.

## Sources

- [License: MIT](https://github.com/sparklemotion/nokogiri/blob/main/LICENSE)
- [Project website](https://nokogiri.org/)
- [README](https://github.com/sparklemotion/nokogiri/blob/main/README.md)
- [Releases](https://github.com/sparklemotion/nokogiri/releases)
- [sparklemotion/nokogiri on GitHub](https://github.com/sparklemotion/nokogiri)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sparklemotion-nokogiri