Explanation

These pages explain how turbohtml is built and why it makes the choices it does: where the C core earns its keep, how the parser, tree model, query engines, serializers, and the free-threaded build fit together, and which trade-offs each one accepts. Start here for the why; the Reference has the what.

When to reach for turbohtml, and when not

turbohtml parses, queries, edits, and serializes HTML through a fast, typed, WHATWG-conformant core. Reach for it when you parse real-world markup and want the tree a browser builds (the html5lib suite passes, so malformed input recovers the way it does in a browser rather than the way libxml2 guesses); when speed matters (the Performance page has the figures); when you want a modern typed API with one name per concept, __match_args__ on every node, and full type stubs, alongside the free-threaded build; or when you escape, unescape, or tokenize on a hot path and want a drop-in several times faster than the standard library.

It is the wrong tool in a few honest cases:

  • You need XSLT, schema validation, or C14N. turbohtml gives CSS selectors, the find filter grammar, and an XPath 1.0 engine, but none of lxml’s wider XML toolchain. Code that leans on those should stay on lxml.

  • You depend on `BeautifulSoup <https://www.crummy.com/software/BeautifulSoup/>`_’s ecosystem or its forgiving, duck-typed API. bs4 swaps parser backends, integrates with a long tail of tools, and accepts almost any shape; turbohtml is one conformant parser with a sealed, typed hierarchy. Code written to bs4’s contract needs the Migrating to turbohtml guide, not a drop-in import.

  • You need a decades-hardened dependency. lxml and BeautifulSoup have been battle-tested for years across every platform and corner case; turbohtml is young.

  • HTML is not your bottleneck. If parsing is a rounding error in your workload, the library you already use is fine. turbohtml’s advantage is speed and a typed API; if you need neither, switching costs more than it saves.