Cheerio: A jQuery-Style HTML Parser for Node
/cheerio
Cheerio is the library you reach for when you need to scrape or transform HTML without spinning up a browser. It implements a subset of jQuery's API on top of parse5, so anyone who has written $('.foo').text() already knows how to use it. No JavaScript execution, no CSS rendering, no layout — just markup in, markup out. For static-HTML scraping it's hard to beat; for JS-heavy sites you still need Puppeteer or Playwright.
What is Cheerio?
Cheerio is a Node.js library that parses HTML and XML into a jQuery-style API you can query and mutate on the server. It loads a document string with cheerio.load(), then lets you select elements with CSS selectors via parse5 (or the more forgiving htmlparser2) and read or change content, attributes, and classes. No live DOM, no browser, no JavaScript execution. Per the README, it runs in both server and browser environments.
Key features: jQuery syntax, fast parsing, flexible input
- ✓Implements a subset of core jQuery's API, so $('h2.title').text() and $('h2').addClass('welcome') work the way they would in a browser script.
- ✓Parses with parse5 by default and can switch to htmlparser2 for HTML that doesn't follow spec — real-world scraped pages, not just clean markup.
- ✓Runs in both server and browser environments, per the README.
- ✓Renders back to HTML with .html(), to outerHTML via .prop('outerHTML'), or to plain text with .text().
- ✓No full DOM-tree overhead — the README describes the model as simple and consistent, which is why parsing and manipulation stay fast.
- ✓Selector scoping via $(selector, context, root) lets you search within a subtree instead of the whole document.
Common use cases: scraping, data extraction, testing
- •Web scraping — pulling structured data out of HTML pages you don't control.
- •Data extraction pipelines that need specific fields from many pages at once.
- •Testing server-rendered HTML output without booting a browser.
- •Server-side templating or post-processing HTML before it's sent to a client.
Installing Cheerio
Install with a package manager: npm install cheerio, or bun add cheerio, or deno install cheerio. Per the README it ships as an ES module (import * as cheerio from 'cheerio') and also works with require() in CommonJS environments.
Parsing HTML and selecting elements
Load a document string with const $ = cheerio.load(html), then use jQuery-style selectors — $('.apple', '#fruits').text() searches inside the #fruits context. Read attributes with .attr('class'), grab inner markup with .html(), or render the whole document again with $.html(). That's the whole workflow. Cheerio's DOM nodes also expose familiar properties: tagName, parentNode, childNodes, previousSibling, nextSibling, and more, so code written for browser-like traversal mostly just works.
Strengths
- ✓jQuery syntax means near-zero ramp-up time for anyone who's used jQuery before.
- ✓Wrapping parse5 with an optional htmlparser2 fallback means it copes with messy, real-world HTML instead of just clean documents.
- ✓MIT license, so there's no ambiguity about using it in commercial scraping or data pipelines.
- ✓Works the same whether you're in Node or a browser bundle, per the README.
What Cheerio cannot do
- △No JavaScript execution — if the data you need is injected by a client-side script, Cheerio never sees it; you need Puppeteer or Playwright instead.
- △No CSS rendering or layout, so anything that depends on computed styles, visibility, or viewport size is out of scope.
- △It isn't a full DOM implementation — only the API surface the README documents (a jQuery subset) is guaranteed to behave like jQuery.
- △The README's 'Cheerio in the real world' adopter list lives on the wiki, not the repo, so checking who runs it in production takes an extra click.
Alternatives: jsdom, Puppeteer, and other parsers
Frequently asked questions
Cheerio is free and open source, released under the MIT license. That means you can use it in commercial or closed-source projects without paying for it or open-sourcing your own code, as long as you keep the license notice.
Cheerio works in both server and browser environments, according to its README — it isn't limited to Node.js. It has no dependency on a live DOM or window object, so the same parsing and selector code runs wherever you load it.
Cheerio implements a subset of jQuery's own API — the same selector syntax and methods like .text(), .attr(), and .addClass() — but it operates on a document string you load explicitly with cheerio.load(), not a live browser DOM. There's no event handling or AJAX, just parsing and markup manipulation.
Cheerio wraps parse5 for HTML parsing by default and can optionally use htmlparser2, a more forgiving parser, instead. Both are separate libraries Cheerio builds its jQuery-style API on top of, per the README.
Cheerio can parse nearly any HTML or XML document, per its README, especially when configured to use the forgiving htmlparser2 parser instead of the stricter parse5 default. That flexibility targets messy, real-world markup, not just clean, spec-valid documents.
The README describes Cheerio as blazingly fast because it works with a simple, consistent DOM model rather than a full browser-grade implementation. It doesn't give a benchmark number against jsdom, but that lighter model instead of full DOM/CSSOM fidelity is the trade-off the speed claim rests on.
The problem it solves
Node scripts that need to read data out of HTML don't have a built-in DOM, and pulling in a real browser (Puppeteer, a headless Chrome instance) just to run querySelectorAll is expensive for pages that never needed JavaScript in the first place. Cheerio fills that specific gap — jQuery-style querying without a browser underneath, for the large share of HTML that's already fully formed by the time it reaches you.
Who should try it — and who should skip
Reach for Cheerio if you're pulling data out of static or server-rendered HTML in a Node project and already think in jQuery selectors — it gets you querying a document in minutes. Skip it if the site you're targeting renders its content with client-side JavaScript; Cheerio has no execution engine, so you'd just be parsing an empty shell.
Related repositories
Is cheerio worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of cheerio.