JustHTML
HTML from the real web is messy. It is often malformed, user supplied, scraped from unknown pages, or headed for a browser where small parsing differences can become security bugs.
JustHTML gives Python projects one small dependency for the common HTML jobs:
- parse HTML like a browser, including broken markup
- sanitize untrusted HTML by default
- query with CSS selectors
- transform, serialize, extract text, or convert to Markdown
- run anywhere Python runs, with no C extension and no system package to install
pip install justhtml
Requires Python 3.10 or later.
Documentation | Comparison | Playground | Security policy
Why Use It?
Most Python HTML libraries optimize for one part of the problem.
html.parser is built in, but not HTML5-correct. BeautifulSoup is convenient, but depends heavily on the parser underneath. lxml and C/Rust-backed parsers are fast, but usually leave sanitization as a separate concern. html5lib and Bleach shaped the Python ecosystem, but both are no longer the obvious foundation for new projects.
JustHTML is for applications that want a boring, inspectable, pure-Python default:
- Correct parsing: browser-style HTML5 recovery, tested against the web platform html5 treebuilder tests.
- Safe by default:
JustHTML(html)sanitizes before you query or serialize. - One DOM: parse once, then sanitize, query, transform, serialize, extract text, or produce Markdown.
- Easy deployment: zero runtime dependencies, no compiler, works on PyPy and Pyodide.
- Honest tradeoff: if you are parsing terabytes of trusted HTML, use a C/Rust parser. If you need reliable handling of untrusted or malformed HTML inside a Python app, use JustHTML.
Real-world signal: Mozilla Support migrated from Bleach to JustHTML in Kitsune, the Django application behind support.mozilla.org.
Quick Start
from justhtml import JustHTML
doc = JustHTML(
"<p>Hello<script>alert(1)</script> "
"<a href='javascript:alert(1)'>bad</a> "
"<a href='https://example.com'>ok</a></p>",
fragment=True,
)
print(doc.to_html(pretty=False))
# => <p>Hello <a>bad</a> <a href="https://example.com">ok</a></p>
Sanitization is enabled by default. Disable it only for trusted input:
doc = JustHTML("<main><p class='intro'>Hello</p></main>", sanitize=False)
intro = doc.query_one("p.intro")
print(intro.to_text())
# => Hello
What You Can Do
from justhtml import JustHTML, Linkify, SetAttrs, Unwrap
doc = JustHTML(
"<p>Hello <span>world</span> example.com</p>",
fragment=True,
sanitize=False,
transforms=[
Unwrap("span"),
Linkify(),
SetAttrs("a", rel="nofollow"),
],
)
print(doc.to_html(pretty=False))
# => <p>Hello world <a href="http://example.com" rel="nofollow">example.com</a></p>
JustHTML includes:
- CSS selectors:
query()andquery_one() - Sanitization: allowlisted HTML cleaning, URL policies, inline CSS controls
- Transforms: unwrap, drop, edit attributes, linkify, compose cleanup pipelines
- Text output:
to_text()and Markdown generation - Builder API: construct nodes directly from Python
- Streaming: process large inputs incrementally
- Bleach migration guide: move existing sanitizer code to JustHTML policies
Command Line
# Pretty-print an HTML file
justhtml index.html
# Parse from stdin
curl -s https://example.com | justhtml -
# Extract text from selected nodes
justhtml index.html --selector "main p" --format text
# Convert selected HTML to Markdown
justhtml index.html --selector "article" --format markdown
Correctness
JustHTML is tested against the web platform html5 treebuilder tests, plus html5lib serializer/encoding fixtures and project-specific sanitizer, selector, transform, CLI, and regression tests.
The current test suite enforces 100% combined line and branch coverage, including the parser engine. The parser engine additionally requires exact agreement with the reference path across the web platform html5 treebuilder suite. See Correctness Testing for details.
Documentation
- Quickstart
- Comparison
- API Reference
- Sanitization & Security
- Migrating from Bleach
- Command Line
- Full documentation site
Security
JustHTML sanitizes by default, but output safety still depends on where you put it. HTML body output is not automatically safe inside JavaScript, CSS, URL attributes, or other contexts.
For the supported-version policy and vulnerability reporting, see SECURITY.md.
License
MIT. Free to use for commercial and non-commercial projects.
1 maintainer
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-3.4.0.tar.gz.
File metadata
- Download URL: justhtml-3.4.0.tar.gz
- Upload date:
- Size: 914.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5a5e373271f284454cf993a220b8687e4bbc1fbb9790ce95bebc4348cebc9b73
|
|
| MD5 |
b7b69131ef0a08de747841ce2f8e7523
|
|
| BLAKE2b-256 |
603b54bc355cbfe64aba01fb94acac704e8d53edb28bb4d1335edec1644de4be
|
Provenance
The following attestation bundles were made for justhtml-3.4.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-3.4.0.tar.gz -
Subject digest:
5a5e373271f284454cf993a220b8687e4bbc1fbb9790ce95bebc4348cebc9b73 - Sigstore transparency entry: 2142604518
- Sigstore integration time:
-
Permalink:
EmilStenstrom/justhtml@94d12bcf0eeda0dda371c548ee397d790e6d76b5 -
Branch / Tag:
refs/tags/v3.4.0 - Owner: https://github.com/EmilStenstrom
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@94d12bcf0eeda0dda371c548ee397d790e6d76b5 -
Trigger Event:
release
-
Statement type:
File details
Details for the file justhtml-3.4.0-py3-none-any.whl.
File metadata
- Download URL: justhtml-3.4.0-py3-none-any.whl
- Upload date:
- Size: 156.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fcdf032fd30e480727b272e7b796fe5fb22013dfd5b765493e52cdeac64b87a8
|
|
| MD5 |
a0e24980cec99a5d083e68a9aecdbcd3
|
|
| BLAKE2b-256 |
724065193f46838e75ff23ce929dd6350af54a3f1929f6ab7f5585d9956e5f7a
|
Provenance
The following attestation bundles were made for justhtml-3.4.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-3.4.0-py3-none-any.whl -
Subject digest:
fcdf032fd30e480727b272e7b796fe5fb22013dfd5b765493e52cdeac64b87a8 - Sigstore transparency entry: 2142604538
- Sigstore integration time:
-
Permalink:
EmilStenstrom/justhtml@94d12bcf0eeda0dda371c548ee397d790e6d76b5 -
Branch / Tag:
refs/tags/v3.4.0 - Owner: https://github.com/EmilStenstrom
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@94d12bcf0eeda0dda371c548ee397d790e6d76b5 -
Trigger Event:
release
-
Statement type:
