A pure Python HTML5 parser that just works.

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for EmilStenstrom from gravatar.com EmilStenstrom

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License
  • Author: Emil Stenström
  • Requires: Python >=3.10
  • Provides-Extra: benchmark , dev
Classifiers
Report project as malware

Project description

JustHTML

A pure Python HTML5 parser that just works. No C extensions to compile. No system dependencies to install. No complex API to learn.

📖 Read the full documentation here

Why use JustHTML?

  • Just... Correct ✅ — Spec-perfect HTML5 parsing with browser-grade error recovery — passes the official 9k+ html5lib-tests suite, with 100% line+branch coverage. (Correctness)

  • Just... Python 🐍 — Pure Python, zero dependencies — no C extensions or system libraries, easy to debug, and works anywhere Python runs (including PyPy and Pyodide). (Quickstart)

  • Just... Secure 🔒 — Safe-by-default output for untrusted HTML — built-in Bleach-style allowlist sanitization on to_html() / to_markdown() (override with safe=False), plus URL/CSS rules. (Sanitization & Security)

  • Just... Query 🔍 — CSS selectors out of the box — one method (query()), familiar syntax (combinators, groups, pseudo-classes), and plain Python nodes as results. (CSS Selectors)

  • Just... Fast Enough ⚡ — Fast for the common case (fastest pure-Python HTML5 parser available); for terabytes, use a C/Rust parser like html5ever. (Benchmarks)

Comparison to other parsers

Parser HTML5 Compliance Pure Python? Speed Query API Notes
JustHTML ✅ 100% ✅ Yes ⚡ Fast ✅ CSS selectors It just works. Correct, easy to install, and fast enough.
html5lib 🟡 88% ✅ Yes 🐢 Slow ❌ None The reference implementation. Very correct but quite slow.
html5_parser 🟡 84% ❌ No 🚀 Very Fast 🟡 XPath (lxml) C-based (Gumbo). Fast and mostly correct.
selectolax 🟡 68% ❌ No 🚀 Very Fast ✅ CSS selectors C-based (Lexbor). Very fast but less compliant.
BeautifulSoup 🔴 4% ✅ Yes 🐢 Slow 🟡 Custom API Wrapper around html.parser. Not spec compliant.
html.parser 🔴 4% ✅ Yes ⚡ Fast ❌ None Standard library. Chokes on malformed HTML.
lxml 🔴 1% ❌ No 🚀 Very Fast 🟡 XPath C-based (libxml2). Fast but not HTML5 compliant.

Compliance scores from a strict run of the html5lib-tests tree-construction fixtures (1,743 non-script tests). See benchmarks/correctness.py and docs/correctness.md for details.

Browser engine agreement (tree-construction, pass/(pass+fail), 2025-12-30):

Engine Tests Passed Agreement Notes
Chromium 1763/1770 99.6% DOMParser / contextual fragment (via Playwright)
WebKit 1741/1770 98.4% DOMParser / contextual fragment (via Playwright)
Firefox 1727/1770 97.6% DOMParser / contextual fragment (via Playwright)

Browser numbers from justhtml-html5lib-tests-bench on the upstream html5lib-tests/tree-construction corpus (excluding 12 scripting-enabled cases).

Installation

Requires Python 3.10 or later.

pip install justhtml

Quick Example

from justhtml import JustHTML

doc = JustHTML("<html><body><p class='intro'>Hello!</p></body></html>")

# Query with CSS selectors
for p in doc.query("p.intro"):
    print(p.name)        # "p"
    print(p.attrs)       # {"class": "intro"}
    print(p.to_html())   # <p class="intro">Hello!</p>

See the Quickstart Guide for more examples including tree traversal, streaming, and strict mode.

Command Line

If you installed JustHTML (for example with pip install justhtml or pip install -e .), you can use the justhtml command. If you don't have it available, use the equivalent python -m justhtml ... form instead.

# Pretty-print an HTML file
justhtml index.html

# Parse from stdin
curl -s https://example.com | justhtml -

# Select nodes and output text
justhtml index.html --selector "main p" --format text

# Select nodes and output Markdown (subset of GFM)
justhtml index.html --selector "article" --format markdown

# Select nodes and output HTML
justhtml index.html --selector "a" --format html

# Example: extract Markdown from GitHub README HTML
curl -s https://github.com/EmilStenstrom/justhtml/ | justhtml - --selector '.markdown-body' --format markdown | head -n 15

Output:

# JustHTML

[](#justhtml)

A pure Python HTML5 parser that just works. No C extensions to compile. No system dependencies to install. No complex API to learn.

**[📖 Read the full documentation here](/EmilStenstrom/justhtml/blob/main/docs/index.md)**

## Why use JustHTML?

- **Just... Correct ✅** — Spec-perfect HTML5 parsing with browser-grade error recovery — passes the official 9k+ [html5lib-tests](https://github.com/html5lib/html5lib-tests) suite, with 100% line+branch coverage. ([Correctness](/EmilStenstrom/justhtml/blob/main/docs/correctness.md))
- **Just... Python 🐍** — Pure Python, zero dependencies — no C extensions or system libraries, easy to debug, and works anywhere Python runs (including PyPy and Pyodide). ([Quickstart](/EmilStenstrom/justhtml/blob/main/docs/quickstart.md))
- **Just... Secure 🔒** — Safe-by-default output for untrusted HTML — built-in Bleach-style allowlist sanitization on `to_html()` / `to_markdown()` (override with `safe=False`), plus URL/CSS rules. ([Sanitization & Security](/EmilStenstrom/justhtml/blob/main/docs/sanitization.md))

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Acknowledgments

JustHTML started as a Python port of html5ever, the HTML5 parser from Mozilla's Servo browser engine. While the codebase has since evolved significantly, html5ever's clean architecture and spec-compliant approach were invaluable as a starting point. Thank you to the Servo team for their excellent work.

Correctness and conformance work is heavily guided by the html5lib ecosystem and especially the official html5lib-tests fixtures used across implementations.

The sanitization API and threat-model expectations are informed by established Python sanitizers like Bleach and nh3.

The CSS selector query API is inspired by the ergonomics of lxml.cssselect.

License

MIT. Free to use both for commercial and non-commercial use.

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for EmilStenstrom from gravatar.com EmilStenstrom

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License
  • Author: Emil Stenström
  • Requires: Python >=3.10
  • Provides-Extra: benchmark , dev
Classifiers

Release history Release notifications | RSS feed

1.20.0

1.19.0

1.18.0

1.17.0

1.16.0

1.15.0

1.14.0

1.13.0

1.12.0

1.11.0

1.10.0

1.9.1

1.9.0

1.8.0

1.7.0

1.6.0

1.5.0

1.4.0

1.3.0

1.2.0

1.1.0

1.0.0

0.40.0

0.39.0

0.38.0

0.37.0

0.36.0

0.35.0

0.34.0

0.33.0

0.32.0

0.31.0

0.30.0

0.29.0

0.28.0

0.27.0

0.26.0

0.25.0

0.24.0

This version

0.23.0

0.22.0

0.21.0

0.20.0

0.19.0

0.18.0

0.17.0

0.16.0

0.15.0

0.14.0

0.13.1

0.13.0

0.12.0

0.11.0

0.10.0

0.9.0

0.8.0

0.7.0

0.6.0

0.5.2

0.5.1

0.5.0

0.4.0

0.3.0

0.2.0

0.1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

justhtml-0.23.0.tar.gz (238.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

justhtml-0.23.0-py3-none-any.whl (89.7 kB view details)

Uploaded Python 3

File details

Details for the file justhtml-0.23.0.tar.gz.

File metadata

  • Download URL: justhtml-0.23.0.tar.gz
  • Upload date:
  • Size: 238.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for justhtml-0.23.0.tar.gz
Algorithm Hash digest
SHA256 648b9000d420bc100fffb2ac5be412ee8d22cd3f17d446160b47e605eca0e674
MD5 bd909dc17764b809da105a89ebe0e29b
BLAKE2b-256 baf7e3249a1500cb7e7bdc439403339a8603edabec44acd0fb322efd176f45f0

See more details on using hashes here.

Provenance

The following attestation bundles were made for justhtml-0.23.0.tar.gz:

Publisher: publish.yml on EmilStenstrom/justhtml

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file justhtml-0.23.0-py3-none-any.whl.

File metadata

  • Download URL: justhtml-0.23.0-py3-none-any.whl
  • Upload date:
  • Size: 89.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for justhtml-0.23.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9d101aafd7b90c5ba9ee27fd19c552e76f619988212f3fd7c97a749e9cb6e295
MD5 53df51efe9738e1cff842539d3cf36f2
BLAKE2b-256 eb7474106a8e315447b75a054b4096367a203035bf1801e3c73ebe1989a3eff7

See more details on using hashes here.

Provenance

The following attestation bundles were made for justhtml-0.23.0-py3-none-any.whl:

Publisher: publish.yml on EmilStenstrom/justhtml

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page