# Cheerio

> Cheerio is a fast, flexible, and elegant Node.js library for parsing and manipulating
> HTML and XML with a jQuery-compatible API. It parses markup into a traversable,
> manipulable DOM-like structure and serializes it back to markup. It is MIT licensed,
> distributed as the `cheerio` npm package, and maintained under the cheeriojs GitHub
> organization. Cheerio is a LIBRARY, not a hosted service: it has no HTTP API, no base
> URL, no API keys, no rate limits and no pricing. It never executes scripts, evaluates
> expressions, or touches the network — the one exception being `fromURL`, which makes
> the request you ask it to make.

Generated by API Evangelist from the project's own published surface on 2026-09-05.
No OpenAPI exists for Cheerio and none is published — see the note at the end.

## Install

- [cheerio on npm](https://www.npmjs.com/package/cheerio): `npm install cheerio` — latest 1.2.0, published 2026-01-23, MIT
- [cheerio/slim](https://cheerio.js.org/docs/advanced/configuring-cheerio/): htmlparser2-only export that leaves parse5 out of the bundle, for browsers
- Runtime: Node.js >= 18.17; a browser build ships in the package; TypeScript types are bundled

## Loading documents

- [Loading Documents](https://cheerio.js.org/docs/basics/loading/): which entrypoint to use for which input
- `load(string)` — you already have the markup as a string. The only method available in the browser.
- `loadBuffer(Buffer)` — raw bytes, unknown encoding; runs the HTML encoding sniffing algorithm.
- `stringStream(stream)` — streaming decoded text, known encoding.
- `decodeStream(stream)` — streaming raw bytes, unknown encoding.
- `fromURL(url)` — Cheerio fetches the page for you. Node.js only.

## Core documentation

- [Introduction](https://cheerio.js.org/docs/intro): what Cheerio is and is not
- [Selecting Elements](https://cheerio.js.org/docs/basics/selecting/): CSS selectors, the same syntax as `document.querySelectorAll`, plus jQuery extensions
- [Traversing](https://cheerio.js.org/docs/basics/traversing/): moving around the tree
- [Manipulation](https://cheerio.js.org/docs/basics/manipulation/): changing attributes, text and markup
- [Extract](https://cheerio.js.org/docs/basics/extract/): pulling structured data out of a document
- [Troubleshooting](https://cheerio.js.org/docs/basics/troubleshooting/)
- [Configuring Cheerio](https://cheerio.js.org/docs/advanced/configuring-cheerio/): parse5 vs htmlparser2, fragment mode, XML mode
- [Extending Cheerio](https://cheerio.js.org/docs/advanced/extending-cheerio/): plugins
- [Security](https://cheerio.js.org/docs/advanced/security/): what Cheerio does and does not protect you from

## API reference

- [API index](https://cheerio.js.org/docs/api/)
- [CheerioAPI interface](https://cheerio.js.org/docs/api/interfaces/cheerioapi/)
- [Cheerio class](https://cheerio.js.org/docs/api/classes/cheerio/)
- [CheerioOptions](https://cheerio.js.org/docs/api/interfaces/cheeriooptions/)
- [Htmlparser2Options](https://cheerio.js.org/docs/api/interfaces/htmlparser2options/)
- [load](https://cheerio.js.org/docs/api/variables/load/), [fromURL](https://cheerio.js.org/docs/api/functions/fromurl/), [loadBuffer](https://cheerio.js.org/docs/api/functions/loadbuffer/), [decodeStream](https://cheerio.js.org/docs/api/functions/decodestream/), [stringStream](https://cheerio.js.org/docs/api/functions/stringstream/), [contains](https://cheerio.js.org/docs/api/functions/contains/), [merge](https://cheerio.js.org/docs/api/functions/merge/)

## Rules an agent must follow

- Cheerio is NOT a sanitizer. `$.html()` output is exactly as trustworthy as its input:
  `<script>` and `onerror` attributes survive parsing and serialization. Run scraped
  markup through sanitize-html or DOMPurify before rendering it in a browser.
- `html()`, `append()`, `prepend()`, `before()`, `after()`, `replaceWith()` and `wrap()`
  parse their argument AS MARKUP. Passing user input to any of them injects whatever tags
  it contains. Use `text()` when you mean text.
- `text()` narrows the problem but does not remove it — the returned string can still
  contain `<`, `>` and `"`. Assign it to a text sink or escape it for its context.
- Never build a selector from untrusted input. Quoting is not enough: a `"` in the value
  closes the attribute selector and the rest is parsed as more selector syntax.
- HTML is parsed by parse5 (browser-conformant tree construction); XML is parsed by
  htmlparser2 (faster, more forgiving, not a conformant XML processor).
- `load` wraps input in `<html>/<head>/<body>` by default. Pass `false` as the third
  argument to parse a fragment instead.

## Project

- [Website and docs](https://cheerio.js.org/)
- [Blog](https://cheerio.js.org/blog/) — [RSS](https://cheerio.js.org/blog/rss.xml)
- [Cheerio 1.0 announcement](https://cheerio.js.org/blog/cheerio-1.0/)
- [GitHub organization](https://github.com/cheeriojs)
- [Repository](https://github.com/cheeriojs/cheerio)
- [Releases / changelog](https://github.com/cheeriojs/cheerio/releases)
- [Issues](https://github.com/cheeriojs/cheerio/issues)
- [Discussions](https://github.com/cheeriojs/cheerio/discussions)
- [Contributing guide](https://github.com/cheeriojs/cheerio/blob/main/CONTRIBUTING.md)
- [Security policy](https://github.com/cheeriojs/cheerio/blob/main/SECURITY.md) — report via Tidelift or GitHub private vulnerability reporting; never a public issue
- [Threat model](https://github.com/cheeriojs/cheerio/blob/main/THREAT_MODEL.md)
- [Incident response plan](https://github.com/cheeriojs/cheerio/blob/main/INCIDENT_RESPONSE.md)
- [License: MIT](https://github.com/cheeriojs/cheerio/blob/main/LICENSE)
- [Sponsors](https://cheerio.js.org/sponsors/)

## API Evangelist artifacts

- [apis.yml](https://raw.githubusercontent.com/api-evangelist/cheerio/refs/heads/main/apis.yml)
- packages/cheerio-packages.yml — npm distribution, versions and publish dates
- conventions/cheerio-conventions.yml — parser selection, selector rules, output-safety rules
- conformance/cheerio-conformance.yml — WHATWG HTML, encoding sniffing, CSS selectors, semver
- lifecycle/cheerio-lifecycle.yml — semver policy and supported versions
- changelog/cheerio-changelog.yml — recent releases
- security/cheerio-vulnerability-disclosure.yml — disclosure process
- well-known/cheerio-well-known.yml — recorded discovery-surface absence (every path 404)

## No machine-readable API contract

Cheerio publishes no OpenAPI, AsyncAPI, GraphQL SDL, MCP server or A2A agent card, and
none should be expected: there is no service to describe. Full contract discovery was run
against cheerio.js.org on 2026-09-05 — /openapi.json, /swagger.json, /api-docs, /llms.txt,
/apis.json, /apis.yml and every named /.well-known path — and every one returned 404.
The machine-readable contract for this project is its bundled TypeScript type
declarations, shipped inside the npm package.