Can I Use XPath Selectors in Cheerio?
Cheerio is a fast, lightweight library for parsing and manipulating HTML and XML in Node.js.
A common question is whether it accepts XPath expressions. The short answer is no: Cheerio's selector engine is built around CSS selectors, and the project has no plan to add XPath support. This guide explains what that means in practice and shows the supported way to select elements in both HTML and XML documents.
The short answer
Cheerio does not accept XPath expressions. If you pass an XPath string such as //book/title to $(), it will not be interpreted as XPath. The maintainers have stated in public GitHub issues that XPath support is not on the roadmap. Instead, Cheerio uses CSS selectors, the same selector syntax you would use with document.querySelectorAll in a browser.
Parsing XML with Cheerio
XPath is often associated with XML, but you can still parse XML documents with Cheerio using CSS selectors. Pass the xml: true option to cheerio.load() so Cheerio treats the input as XML rather than HTML. The example below loads a small bookstore document and selects every title element that is a direct child of a book element. The selector book > title is a CSS child combinator, not XPath.
Choosing between XPath and CSS selectors
Use the following checklist when deciding how to locate elements:
- If your existing codebase or tooling already relies on XPath expressions, Cheerio is not a drop-in replacement; you would need to translate those expressions to CSS selectors or use a different parser.
- If you are starting fresh with Cheerio, write CSS selectors. They cover element names, classes, IDs, attributes, descendant and child relationships, and sibling combinators.
- If you need XML-specific behavior such as case-sensitive tag names, set
xml: truewhen loading the document. - If a selector returns nothing, first confirm the document was loaded in the correct mode (HTML vs XML) before assuming the selector syntax is wrong.
A common failure distinction
Two different problems can look similar when a selection returns an empty result. The first is an unsupported selector: passing an XPath expression to Cheerio will not throw a helpful 'XPath not supported' error; it simply will not match. The second is a valid CSS selector that does not match because the document structure differs from what you expected, or because the document was parsed in HTML mode when it should have been parsed in XML mode. Checking the load options and the actual document structure usually resolves the confusion faster than rewriting the selector.
Cheerio load options and selector methods at a glance
The table below summarizes the inputs and outputs used in the XML example. It is a reader aid, not a replacement for the official Cheerio documentation.
| Item | Value / behavior |
|---|---|
cheerio.load(input, options) | Loads an HTML or XML string and returns a selector function |
options.xml | When true, parses the input as XML |
$('book > title') | CSS child-combinator selector returning matching elements |
.each((i, el) => ...) | Iterates over matched elements |
$(el).text() | Returns the text content of an element |
| Output | Practical Python Projects, Intermediate Python |
Frequently asked questions
Does Cheerio support XPath?
No. Cheerio uses CSS selectors and does not accept XPath expressions. The project has stated there is no plan to add XPath support.
Can I parse XML with Cheerio?
Yes. Pass xml: true to cheerio.load() and use CSS selectors to find elements. For example, $('book > title') selects title elements that are direct children of a book element.
Why does my XPath selector return nothing in Cheerio?
Because Cheerio does not interpret XPath. The expression is treated as an unrecognized selector and matches nothing. Rewrite the expression as a CSS selector, or use a parser that supports XPath.