Install & Compatibility
Where this runs
tested against v1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.232s · 19.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.208s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
html5lib
✓ import html5lib
HTMLParser
✓ from html5lib.html5parser import HTMLParser
✗ import html5lib.HTMLParser
While 'html5lib.HTMLParser' might work due to re-exports, direct import from 'html5lib.html5parser' is clearer and avoids potential ambiguity.
getTreeBuilder
✓ from html5lib import getTreeBuilder
✗ from html5lib.treebuilders import getTreeBuilder
The `getTreeBuilder` function is re-exported at the top-level `html5lib` module for convenience.
This quickstart demonstrates basic HTML parsing using `html5lib.parse` for the default `xml.etree` output, and how to use `html5lib.HTMLParser` with a custom treebuilder like `xml.dom.minidom`. It also shows how to enable strict parsing to catch HTML errors. By default, `html5lib` provides an `xml.etree` element instance, but `xml.dom.minidom` and `lxml.etree` are also supported via treebuilders.
import html5lib
# Parse a simple HTML string
document = html5lib.parse("<p>Hello <b>World</b>!</p>")
print(f"Parsed document tag: {document.tag}")
print(f"First child's tag: {document[0].tag}")
print(f"First child's text: {document[0].text}")
# Parse with a specific treebuilder (e.g., xml.dom.minidom)
parser = html5lib.HTMLParser(tree=html5lib.getTreeBuilder("dom"))
minidom_document = parser.parse("<p>Another <i>example</i>.</p>")
# Accessing an element using minidom structure
p_tag = minidom_document.getElementsByTagName('p')[0]
print(f"Minidom document P tag: {p_tag.tagName}")
# Example with strict parsing (raises exceptions on errors)
try:
strict_parser = html5lib.HTMLParser(strict=True)
strict_parser.parse("<div><p>Missing close tag")
except html5lib.html5parser.ParseError as e:
print(f"Strict parsing error: {e}")
Debug
Known issues
breakingSupport for Python 2.6, 3.3, and 3.4 has been dropped in recent versions. Specifically, Python 2.6 support was removed in 1.0.1, and Python 3.3/3.4 support was removed in 1.1.fixUpgrade to Python 3.5+ for html5lib 1.1+.
affects: >=1.0.1, >=1.1
deprecatedThe `html5lib` sanitizer (via `html5lib.serialize(sanitize=True)` and `html5lib.filters.sanitizer`) has been deprecated since version 1.1. Users are recommended to migrate to the `Bleach` library for HTML sanitization.fixMigrate to `Bleach` for sanitization. Note that `Bleach` is not a drop-in replacement and may require tuning due to different default allow lists and escaping behaviors.
affects: >=1.1
breakingThe default DOM treebuilder was removed, meaning `html5lib.treebuilders.dom` is no longer directly supported as a module. Instead, `html5lib.treebuilders.getTreeBuilder("dom")` should be used, which returns a builder using `xml.dom.minidom`.fixReplace direct imports or references to `html5lib.treebuilders.dom` with `html5lib.getTreeBuilder("dom")`. affects: >=1.0b1
gotchaWhen using `html5lib` as a backend for `pandas.read_html()`, you might encounter `ImportError: missing optional dependency html5lib` even if `html5lib` is installed. This often happens if the `html5lib` installation is not correctly recognized by the `pandas` environment or if there are conflicts with other parsers.fixEnsure `html5lib` is installed in the correct environment (e.g., using `pip install html5lib` or `conda install html5lib`). If the issue persists, try installing `BeautifulSoup4` and `lxml` alongside `html5lib` (`pip install "pandas[html]"`) and restarting your kernel/environment.
affects: All versions when used with pandas
gotcha`html5lib` is a pure-Python library and can be significantly slower than alternatives like `lxml` (which is written in C). While `html5lib` provides more specification-compliant parsing, performance-critical applications might prefer `lxml` where strict HTML5 parsing isn't the absolute highest priority.fixFor performance-sensitive applications, consider using `lxml` as the parser directly or as a treebuilder with `html5lib` if some HTML5-specific error handling is still desired. `lxml` can be used as a tree format with `html5lib` by specifying `treebuilder='lxml'`.
affects: All versions
breakingThe `html5lib` library, or a component utilizing it, produced a 'Strict parsing error: Unexpected start tag (div). Expected DOCTYPE.' This error suggests that the parser encountered an HTML tag (like `div`) at the beginning of the document when it was strictly expecting a `<!DOCTYPE html>` declaration. While `html5lib` is generally lenient with malformed HTML and missing DOCTYPEs, this error indicates that a strict parsing mode might be enabled, or the input HTML is severely malformed for the parser's current configuration.fixEnsure that the input HTML document is well-formed and begins with a `<!DOCTYPE html>` declaration if a strict parsing environment is used. If parsing an HTML fragment, consider wrapping it with full `<html><body>...</body></html>` tags, potentially including a DOCTYPE. Review the `html5lib` initialization or the configuration of any library using `html5lib` to check for options that might enable a strict parsing or validation mode, and disable them if lenient parsing is desired.
affects: All versions
breakingAn unexpected 'Strict parsing error: Unexpected start tag (div). Expected DOCTYPE.' occurred during HTML parsing. This error suggests that the the parser encountered a 'div' tag when it was expecting a 'DOCTYPE' declaration, possibly due to malformed HTML input, re-using a parser expecting a new document, or if strict parsing was inadvertently enabled. While html5lib is generally lenient, such a specific 'strict parsing error' indicates a fundamental issue with the input structure or parser configuration.fixEnsure the input HTML is a complete, well-formed HTML5 document, including a correct `<!DOCTYPE html>` declaration at the very beginning. If parsing HTML fragments, ensure the appropriate API (e.g., `parseFragment` if available and applicable) is used instead of one expecting a full document. Verify that no strict parsing options are explicitly or inadvertently enabled (e.g., passing `strict=True` to `HTMLParser` or its methods).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'html5lib'
The 'html5lib' library is not installed in the Python environment being used, or the Python interpreter cannot find it.
fixInstall the library using pip: `pip install html5lib`
ImportError: "html5lib not found, please install it"
This error occurs when a dependent library (like Pandas or BeautifulSoup) attempts to use html5lib, but it is not installed or accessible in the current Python environment.
fixInstall the library using pip: `pip install html5lib`. If it's already installed, ensure your IDE or Jupyter kernel is restarted, or that you are in the correct virtual environment.
AttributeError: module 'html5lib.treebuilders' has no attribute '_base'
This error typically arises from an incompatibility between `html5lib` and `BeautifulSoup4` versions, where `BeautifulSoup4` expects an older internal structure of `html5lib`'s tree builders.
fixUpgrade BeautifulSoup4 to a compatible version (e.g., `pip install --upgrade beautifulsoup4`). If the issue persists, ensure `html5lib` is also updated: `pip install --upgrade html5lib`.
ImportError: cannot import name 'html5lib' from 'pip._vendor'
This error occurs when attempting to import `html5lib` from `pip`'s internal, vendorized modules, which is not intended for direct use by user code.
fixEnsure you are installing `html5lib` as a standalone package (`pip install html5lib`) and importing it directly as `import html5lib`, not from `pip._vendor`.
html5lib.html5parser.ParseError: Unexpected character after attribute value
This specific ParseError indicates that `html5lib` encountered a character in the HTML document that it did not expect immediately after an attribute value, suggesting malformed HTML.
fixInspect the HTML input for syntax errors, especially around attribute declarations. If parsing highly irregular HTML, you might set `strict=False` when initializing the parser if using `HTMLParser` directly (e.g., `parser = html5lib.HTMLParser(strict=False)`), though this is generally not recommended for robust parsing.
Upgrade
Version history
1.1latest on PyPI · released Jun 22, 2020
Audit
Dependencies
sixrequiredSupports Python 2.x and 3.x compatibility in older versions; explicitly added as a dependency for >=1.9.
webencodingsrequiredRequired dependency for decoding input byte streams, ensuring compliance with the Encoding Standard (since 0.99999999/1.0b9).
lxmloptionalOptional, for improved performance and lxml.etree tree format support (not on PyPy due to segfaults).
genshioptionalOptional, provides a treewalker (but not a builder).
chardetoptionalOptional, for heuristic character encoding detection as a fallback.