Skip to content
Get packs

Guide · Open source

How to use Cheerio: parse and edit HTML in Node.js

Updated · written with AI from the project's own documentation and checked against our catalogue data

Cheerio is an open-source JavaScript and TypeScript library that loads HTML or XML text into a tree you can search and change using jQuery-style selectors. This guide explains what it is good for, how to get it set up with Node.js, and where it stops being the right tool. By the end you will know when Cheerio fits your task and how to start using it.

Cheeriocheeriojs/cheerio · ★ 30.5k · MIT

Quick start

  1. 1Check prerequisites. Make sure Node.js is installed, since it is the listed prerequisite.
  2. 2Get the code or add the package. Clone the repository with the git command shown above, or install Cheerio into your project with a package manager.
  3. 3Save a sample HTML page. Save or fetch the static HTML page you want to work with so you can test your selectors on it.
  4. 4Load the HTML. Pass the HTML string to Cheerio so it builds a tree you can query.
  5. 5Select the elements you need. Use jQuery-style selectors to find the text, links or attributes you want.
  6. 6Test on dynamic pages. Confirm the data appears in the raw HTML. If it does not, Cheerio alone will not see it.

What is Cheerio and what does it do?

Cheerio parses HTML or XML text and turns it into a tree that you can query and edit. You select elements with selectors that work like the ones used in jQuery, so if you have written jQuery before, the syntax will feel familiar.

The project describes itself as fast, flexible, and elegant. Developers commonly use it to pull data out of web pages, for example in scrapers, or to modify markup on the server without starting a browser.

Who should use Cheerio?

Cheerio suits JavaScript developers who already know jQuery-style selectors and want to work with static HTML. It is a good match for scripts that extract text or links from pages, server-side processing of HTML or XML, and simple web scrapers built in Node.js.

  • JavaScript developers comfortable with jQuery-style selectors
  • Scripts that extract text or links from static HTML pages
  • Server-side processing of HTML or XML without a browser
  • Simple web scrapers in Node.js

Install Cheerio and check your prerequisites

Cheerio is a library, so you add it to a Node.js project through a package manager. Node.js is the prerequisite listed for this project. The project README provided for this page was empty, so check the homepage at https://cheerio.js.org for the current installation instructions.

The source material for this page includes a repository clone command. You can use it to get a copy of the source code:

git clone https://github.com/cheeriojs/cheerio

Load HTML and select elements

Give Cheerio a string of HTML or XML and it builds a tree you can query. Once loaded, you pick elements with jQuery-style selectors and read their text, attributes or children. Because Cheerio works on the markup you pass in, the page must already contain the content you want.

  • Load your HTML or XML string into Cheerio
  • Select elements with jQuery-style selectors
  • Read text, attributes or child elements from the matches

Edit markup on the server

Cheerio can also modify the tree it has loaded, so you can change markup on the server without a browser. This is useful when you need to clean up or transform HTML before saving or passing it on.

Keep in mind that Cheerio is not a full browser environment. Projects that need full DOM behavior should look at other tools.

Know the limits before you build

Cheerio does not run JavaScript on the page. If a site fills in its content after load, the data you need may not be in the HTML Cheerio receives. This is a general property of HTML parsers rather than something the project README confirmed, so test a page first.

Cheerio is also a developer library, not a point-and-click tool, so non-developers will need a different product.

  • Does not run page scripts
  • Not a full browser or complete DOM environment
  • Requires coding in JavaScript or TypeScript

What people use it for

  • Extracting text or links from a static HTML page
  • Cleaning or transforming HTML on the server before storing it
  • Processing XML documents with familiar selectors
  • Building a simple scraper for pages whose data is in the initial HTML

Frequently asked questions

Is Cheerio free to use?

Cheerio is released under the MIT licence, as listed on its project page. Check the licence file in the repository for the full terms before using it in your project.

What do I need to run Cheerio?

Node.js is the prerequisite listed for this project. You install Cheerio into a Node.js project using a package manager.

Can Cheerio scrape pages that load content with JavaScript?

Not on its own. Cheerio works on the HTML it is given and does not run scripts, so content added after the page loads will not appear. You may need a tool that runs a browser for those pages.

How is Cheerio different from jsdom?

Cheerio is focused on fast parsing and manipulation with jQuery-style selectors and does not aim to provide full browser DOM behavior. The project lists jsdom as a comparable option, which is the better fit if you need a fuller DOM environment.

What are alternatives to Cheerio?

Projects listed as comparable include jsdom, htmlparser2, parse5 and node-html-parser. Pick based on whether you need full DOM behavior, a lower-level parser or a lightweight API.

Why is my selector not finding anything?

First check that the element is present in the raw HTML you loaded. If the content is generated by JavaScript after load, Cheerio will not see it, so confirm the data exists in the page source.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Cheerio is a good choice for JavaScript developers who want to extract or edit data from static HTML or XML using jQuery-style selectors. If you need a full browser environment, a point-and-click scraper, or pages that build their content with JavaScript, pick a different tool such as jsdom or a browser-based option.

Install options & downloads