A pure Python HTML5 parser that just works.
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
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.
📖 Full documentation | 🛝 Try it in the Playground
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)
JustHTML("<p><b>Hi<i>there</b>!", fragment=True).to_html() # => <p><b>Hi<i>there</i></b><i>!</i></p> # Note: fragment=True parses snippets (no <html>/<body> needed)
-
Just... Python 🐍 — Pure Python, zero dependencies — no C extensions or system libraries, easy to debug, and works anywhere Python runs, including PyPy and Pyodide. (Run in the browser)
python -m pip show justhtml | grep -E '^Requires:' # Requires: [intentionally left blank]
-
Just... Secure 🔒 — Safe-by-default output for untrusted HTML — built-in Bleach-style allowlist sanitization on
to_text(),to_html(),to_markdown()(override withsafe=False). Can sanitize inline CSS rules. (Sanitization & Security)JustHTML( "<p>Hello<script>alert(1)</script> " "<a href=\"javascript:alert(1)\">bad</a> " "<a href=\"https://example.com/?a=1&b=2\">ok</a></p>", fragment=True, ).to_html() # => <p>Hello <a>bad</a> <a href="https://example.com/?a=1&b=2">ok</a></p>
-
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)JustHTML( "<main><p class=\"x\">Hi</p><p>Bye</p></main>", fragment=True, ).query("main p.x")[0].to_html() # => <p class="x">Hi</p>
-
Just... Fast Enough ⚡ — Fast for the common case (fastest pure-Python HTML5 parser available); for terabytes, use a C/Rust parser like
html5ever. (Benchmarks)TIMEFORMAT='%3R s' time curl -Ls https://en.wikipedia.org/wiki/HTML \ | python -m justhtml - > /dev/null # 0.365 s
Comparison
| Tool | HTML5 parsing [1][2] | Speed | CSS query | Sanitizes output | Notes |
|---|---|---|---|---|---|
| JustHTML Pure Python |
✅ 100% | ⚡ Fast | ✅ CSS selectors | ✅ Built-in (safe=True) |
Correct, easy to install, and fast enough. |
| Chromium browser engine |
✅ 99% | 🚀 Very Fast | — | — | — |
| WebKit browser engine |
✅ 98% | 🚀 Very Fast | — | — | — |
| Firefox browser engine |
✅ 97% | 🚀 Very Fast | — | — | — |
html5libPure Python |
🟡 88% | 🐢 Slow | 🟡 XPath (lxml) | 🔴 Deprecated | Unmaintained. Reference implementation; Correct but quite slow. |
html5_parserPython wrapper of C-based Gumbo |
🟡 84% | 🚀 Very Fast | 🟡 XPath (lxml) | ❌ Needs sanitization | Fast and mostly correct. |
selectolaxPython wrapper of C-based Lexbor |
🟡 68% | 🚀 Very Fast | ✅ CSS selectors | ❌ Needs sanitization | Very fast but less compliant. |
html.parserPython stdlib |
🔴 4% | ⚡ Fast | ❌ None | ❌ Needs sanitization | Standard library. Chokes on malformed HTML. |
BeautifulSoupPure Python |
🔴 4% (default) | 🐢 Slow | 🟡 Custom API | ❌ Needs sanitization | Wraps html.parser (default). Can use lxml or html5lib. |
lxmlPython wrapper of C-based libxml2 |
🔴 1% | 🚀 Very Fast | 🟡 XPath | 🔴 Not considered safe | Fast but not HTML5 compliant. |
[1]: Parser compliance scores are from a strict run of the html5lib-tests tree-construction fixtures (1,743 non-script tests). See docs/correctness.md for details.
[2]: Browser numbers are from justhtml-html5lib-tests-bench on the upstream html5lib-tests/tree-construction corpus (excluding 12 scripting-enabled cases).
Installation
pip install justhtml
Next: Quickstart Guide, CSS Selectors, Sanitization & Security, or try the Playground.
Requires Python 3.10 or later.
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))
Security
For security policy and vulnerability reporting, please see SECURITY.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 PyPIProject links
GitHub Statistics
Maintainers
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file justhtml-0.30.0.tar.gz.
File metadata
- Download URL: justhtml-0.30.0.tar.gz
- Upload date:
- Size: 265.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7a7c82bcac46686ca80678038c5939b0dfd54de1db08a6f599997aa50a16ce6e
|
|
| MD5 |
00b021666ea2c8ab73bb13d0ca143f36
|
|
| BLAKE2b-256 |
e274845ff11b5b3d5093e0d460c38f8d52e7e0b55690aab89a6fab99fb31c522
|
Provenance
The following attestation bundles were made for justhtml-0.30.0.tar.gz:
Publisher:
publish.yml on EmilStenstrom/justhtml
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
justhtml-0.30.0.tar.gz -
Subject digest:
7a7c82bcac46686ca80678038c5939b0dfd54de1db08a6f599997aa50a16ce6e - Sigstore transparency entry: 789840508
- Sigstore integration time:
-
Permalink:
EmilStenstrom/justhtml@77bba644b996cc3f196fa760e627ac09d622bc75 -
Branch / Tag:
refs/tags/v0.30.0 - Owner: https://github.com/EmilStenstrom
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@77bba644b996cc3f196fa760e627ac09d622bc75 -
Trigger Event:
release
-
Statement type:
File details
Details for the file justhtml-0.30.0-py3-none-any.whl.
File metadata
- Download URL: justhtml-0.30.0-py3-none-any.whl
- Upload date:
- Size: 94.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
87a8202a6d1155890cd7348ed1f2653a70339a468e00e7b499e88259a1f3179e
|
|
| MD5 |
2c4f5a775d0de8a793ed7bf2b1bc363a
|
|
| BLAKE2b-256 |
adb16123f7dbcdca2e16bdd35664c85e11741c92315f207f7f2a5e302571c245
|
Provenance
The following attestation bundles were made for justhtml-0.30.0-py3-none-any.whl:
Publisher:
publish.yml on EmilStenstrom/justhtml
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
justhtml-0.30.0-py3-none-any.whl -
Subject digest:
87a8202a6d1155890cd7348ed1f2653a70339a468e00e7b499e88259a1f3179e - Sigstore transparency entry: 789840511
- Sigstore integration time:
-
Permalink:
EmilStenstrom/justhtml@77bba644b996cc3f196fa760e627ac09d622bc75 -
Branch / Tag:
refs/tags/v0.30.0 - Owner: https://github.com/EmilStenstrom
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@77bba644b996cc3f196fa760e627ac09d622bc75 -
Trigger Event:
release
-
Statement type:
