Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteSome links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Cheerio is a Node.js library for parsing HTML or XML and selecting elements with a jQuery-like API. It is useful when the data you need is already in the markup you receive. It is not a browser: it does not render pages, run JavaScript, load external resources, or apply CSS. That distinction is the key to choosing Cheerio—and to diagnosing empty results.
What is Cheerio, and when should you use it?
Cheerio turns markup into a traversable document structure. You can select elements with CSS selectors, read their text or attributes, move through related nodes, and serialize the resulting document. A common use is extracting fields from server-rendered HTML: for example, product names in headings, article links, or metadata in a page’s source.
Cheerio does not behave like Chrome or another web browser. It does not lay out a visual page, fetch linked stylesheets or images, or execute the JavaScript that might populate a page after its initial response. If the HTML already contains the data, Cheerio is often a straightforward fit. If the data only appears after browser-side code runs, parsing the initial HTML alone cannot reveal it.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Cheerio versus browser automation
Use Cheerio to parse markup you already have or can fetch as HTML. Use a browser automation tool when your task genuinely depends on rendered state—for example, waiting for client-side content, interacting with controls, or taking a screenshot. These approaches solve different problems: a screenshot is a visual artifact, not a substitute for extracting structured text and fields.
#1 Best Overall
If you need a clean visual capture rather than parsed data, ScreenshotNeo is a website screenshot API and MCP server. It is an alternative for capture tasks, not a Cheerio parser.
How do you install Cheerio?
In a Node.js project, install the package with npm:
npm install cheerioThe current official introduction states that Cheerio runs on Node.js 22.19 or later. Check that requirement against the Node.js version used in development, CI, and deployment; a package that installs locally may still fail in an older runtime. The examples below use ECMAScript modules (ESM), the syntax shown in the current introduction.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteTo use ESM, make sure your project is configured for modules—for example, by setting "type": "module" in package.json, or by using an .mjs file. The CommonJS form is const cheerio = require('cheerio'), for projects configured to use require.
How do you load HTML and extract data?
Choose the loading method to fit the data you have. The smallest working example starts with an HTML string:
import * as cheerio from 'cheerio';
const html = `
<article class="post">
<h2 class="title">A useful heading</h2>
<a class="read-more" href="/posts/one">Read more</a>
</article>
`;
const $ = cheerio.load(html);
const title = $('h2.title').text().trim();
const href = $('a.read-more').attr('href');
console.log({ title, href });cheerio.load() parses the supplied string and returns the $ function used for querying. A selector such as h2.title matches headings with class title; .text() reads their text and .attr('href') reads an attribute. If there are multiple matches, use an iteration method such as .each() to process them individually.
Load from a URL
For a Node.js script that should fetch a page itself, cheerio.fromURL(url) is the URL-oriented option:
import * as cheerio from 'cheerio';
const $ = await cheerio.fromURL('https://example.com/');
const title = $('title').text().trim();
console.log(title);A successful fetch only gives Cheerio the response markup; it does not turn the request into a browser session or execute scripts on the page. When you need more control over fetching—such as request policy, headers, retry behavior, or rate limiting—fetch through an HTTP client you manage, then pass its response body to an appropriate Cheerio loader.
Load bytes or streams
Use cheerio.loadBuffer(buffer) when you have raw bytes and the character encoding is uncertain. Use cheerio.stringStream() when decoded text arrives as a stream, or cheerio.decodeStream() when the incoming stream contains raw bytes. These stream APIs let Node.js workflows parse input incrementally rather than requiring the entire response as a string first.
The browser build supports only load; the other loading methods rely on Node.js APIs. Decide which runtime your code will use before selecting an API.
Read, traverse, and serialize
Selectors can be scoped to a parent selection. For example, $('.post').find('.subtitle') searches for a subtitle within the selected post rather than across the whole document. You can also read or modify markup and serialize it with $.html(). This can be useful for normalizing or transforming markup as well as extracting values. Keep selector scope in mind: a search performed inside a selection is relative to that selection.
Why does Cheerio return empty results?
An empty selection means the selector found no matching node in the document Cheerio parsed. It does not necessarily mean the page has no such content when viewed in a browser. Work through these checks in order:
- Inspect the exact input. Log or save the HTML string or response body passed to Cheerio. Confirm that it is the expected page and that it contains the content you want to extract.
- Test the selector against that markup. Check spelling, class names, nesting, and attribute values. A selector copied from a browser inspector may match the rendered DOM but not the initial response HTML.
- Check for client-side rendering. If the page relies on React, Vue, or other browser-side JavaScript to add the target content, that content may not exist in the response Cheerio received. Cheerio does not execute the page’s scripts.
- Check scope and selection size. A selector nested inside
find()or a nested extraction definition is evaluated relative to its current selection. Start with a broad selection, verify it matches, and narrow it one step at a time. - Check what text you are reading. Calling
text()on a broad selection can include text from script and style elements inside that selection. Target the relevant node more narrowly or remove unwanted nodes before reading.
If the required data is absent from the received HTML, first look for an authorized server-rendered endpoint that provides it. If none is suitable and the task requires the rendered page, use browser automation. Do not expect a different CSS selector to recover content that was never present in the parsed markup.
Which parser should you use?
Cheerio uses parse5 by default for HTML. Its documentation describes parse5 as browser-oriented and standards-conforming, making it a sensible default when you want HTML parsing aligned with browser parsing behavior.
Cheerio also offers htmlparser2 for XML and for workloads that benefit from faster, lower-memory, more forgiving parsing. Its error correction can differ from browser parsing. Choose based on the input format and the behavior your task needs, not on an assumption that every parser will construct the same tree from imperfect markup. If output differs from a browser, parser choice and malformed input are among the factors to examine.
How do you scrape responsibly?
Before making requests, review the site’s terms and identify your client. Keep request rates limited, cache responses where appropriate, and collect only what is authorized and necessary for your purpose. These practices reduce unnecessary load and help you stay within applicable operational constraints.
Best Value
Review the site’s /robots.txt rules as part of that process. RFC 9309 defines the Robots Exclusion Protocol and says crawlers are requested to honor rules published there. It also makes clear that robots.txt is not access authorization: a rule in that file neither grants permission to access restricted material nor replaces the site’s terms or other requirements.
Whether a particular scraping activity is lawful depends on factors including jurisdiction, contract terms, authentication, copyright, privacy, the data involved, and how it will be used. There is no site-specific legal determination here. Obtain permission where needed, and seek qualified legal advice if the stakes or uncertainty warrant it.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If you need a screenshot rather than extracted HTML fields, a single ScreenshotNeo request can capture a page without you setting up browser automation. It accepts a URL and returns an image or PDF. The capture can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server also lets AI agents use screenshot tools.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →For example, this cURL request saves a WebP screenshot of Stripe:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for setup and request options. Free includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.
Common Cheerio errors and practical fixes
- The package will not run in deployment: compare the deployed Node.js version with Cheerio’s stated requirement of Node.js 22.19 or later, then align the runtime or deployment environment.
requireorimportfails: use the module system configured by the project. ESM examples useimport; CommonJS projects userequire. Check the project’s module configuration and file extension.- The URL fetch fails: separate the network request from parsing. Confirm that the URL is reachable from the Node.js environment and that the fetch returned the expected response body before diagnosing selectors. For workflows needing custom request handling, fetch with your chosen HTTP client and parse the resulting markup.
- The selector matches in DevTools but not in Cheerio: compare the browser’s live DOM with the original response HTML. Browser-side scripts may have added the content after load; use an authorized endpoint or browser automation if rendering is needed.
- Text contains unexpected content: narrow the selected element and check for nested script or style nodes. Remove unwanted nodes before reading text if necessary.
- Parsed structure differs from browser expectations: verify whether the input is HTML or XML, whether it is malformed, and whether the chosen parser’s error correction is suitable. parse5 is the default HTML parser; htmlparser2 has different behavior.
FAQ
Can Cheerio scrape JavaScript-rendered pages?
Not by running the page’s JavaScript. It can extract data from markup that is present in its input; use an authorized endpoint or browser automation when the data is only generated after page scripts run.
Does Cheerio download images or apply CSS?
No. It parses markup and provides methods to query and manipulate its structure; it does not load external resources or visually render the page.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Can I use Cheerio in a browser?
The browser build supports load for markup strings. The buffer, stream, and URL loading methods rely on Node.js APIs.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
