Registry / web-framework / selectolax

selectolax

JSON →
library0.4.11pypypi✓ verified 24d ago

Selectolax is a fast and lightweight Python library for parsing HTML5 documents with CSS selectors. It leverages Cython bindings to the high-performance Modest and Lexbor engines, with Lexbor being the recommended and actively developed backend. It is actively maintained, with frequent releases addressing bugs and adding features.

pip install selectolax
INSTALL
IMPORT
SIG · SELECTOLAX
S
selectolax
web-frameworkpythonv0.4.11
Install
2.3s avg
Import
34ms
Disk
44MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.4.11 · 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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.034s · 44.7MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.3s · import 0.033s · 46MB
44MB installed
● package 44MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

LexborHTMLParser
from selectolax.lexbor import LexborHTMLParser
from selectolax.parser import HTMLParser
The `LexborHTMLParser` from `selectolax.lexbor` is the recommended and preferred backend, offering better performance and features. The `HTMLParser` from `selectolax.parser` uses the deprecated Modest backend.

This example demonstrates how to parse an HTML string using `LexborHTMLParser`, extract text from specific elements using CSS selectors, and iterate through multiple matching elements to gather data. It also shows how to access attributes and safely handle cases where an element might not be found.

from selectolax.lexbor import LexborHTMLParser html_content = """ <html> <head><title>My Awesome Page</title></head> <body> <h1 id="main-title" data-version="1.0">Welcome!</h1> <div class="post"> <p>This is the first post.</p> <a href="/post/1">Read more</a> </div> <div class="post"> <p>This is the second post.</p> <a href="/post/2">Read more</a> </div> <p class="footer">© 2026</p> </body> </html> """ tree = LexborHTMLParser(html_content) # Get the title title = tree.css_first('title').text() if tree.css_first('title') else 'No Title' print(f"Page Title: {title}") # Get the text of the main heading main_heading = tree.css_first('h1#main-title').text() if tree.css_first('h1#main-title') else 'N/A' print(f"Main Heading: {main_heading}") # Get all post paragraphs and their links posts_data = [] for post_node in tree.css('.post'): paragraph_text = post_node.css_first('p').text() if post_node.css_first('p') else '' link_href = post_node.css_first('a').attrs.get('href') if post_node.css_first('a') else '' posts_data.append({'paragraph': paragraph_text, 'link': link_href}) print("\nPosts Found:") for post in posts_data: print(f"- {post['paragraph']} (Link: {post['link']})")
Debug
Known issues
breakingEmpty HTML tags are now serialized to `<tag value="">` instead of `<tag value>`. This change affects how attributes of empty tags are represented in the output HTML.
fix
Adjust any code that relies on the exact serialization format of empty tags. If you were parsing and then re-serializing, verify that the new format does not break downstream processes.
affects: 0.4.7+
deprecatedThe `HTMLParser` (Modest backend) from `selectolax.parser` is deprecated. Users should migrate to `LexborHTMLParser` from `selectolax.lexbor` for improved performance, features, and continued support.
fix
Replace `from selectolax.parser import HTMLParser` with `from selectolax.lexbor import LexborHTMLParser` and update instantiation accordingly.
affects: 0.4.0+
gotchaThe `css_first()` method returns `None` if no element matches the given CSS selector. Failing to check for `None` before accessing attributes or methods (e.g., `.text()`, `.attrs`) will result in an `AttributeError`.
fix
Always check if the result of `css_first()` is not `None` before proceeding: `node = tree.css_first('selector'); if node: ...`.
affects: All versions
gotchaVersion `0.4.5` was a bugged release and was subsequently yanked from PyPI. Installing or using this specific version is not recommended.
fix
Avoid installing `0.4.5`. Upgrade to `0.4.6` or later, or downgrade to `0.4.4` if necessary.
affects: 0.4.5
gotchaEarlier versions of selectolax (prior to 0.4.6 and 0.4.0) contained memory leaks in the fragment parser and potential segfaults when accessing attributes or performing DOM modifications like `decompose()` or `unwrap()`.
fix
Upgrade to `selectolax` version `0.4.6` or `0.4.7` (or newer) to benefit from these critical memory and stability fixes.
affects: <0.4.6, <0.4.0
gotchaInstallation via `pip install selectolax` might fail with compilation errors, especially if installing an outdated version on a newer Python environment, or if Cython is not readily available.
fix
If compilation errors occur, try `pip install selectolax[cython]` to explicitly install Cython, which can help resolve these issues.
affects: All versions (under specific conditions)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'selectolax'
The selectolax package is not installed in the current Python environment.
fix
pip install selectolax
ImportError: cannot import name 'HTMLParser' from 'selectolax'
The HTMLParser class is located within the `selectolax.parser` submodule, not directly under the top-level `selectolax` package.
fix
from selectolax.parser import HTMLParser
AttributeError: 'Node' object has no attribute 'text'
In selectolax, the text content of a Node object is accessed by calling the `text()` method, not by directly accessing a `text` attribute.
fix
Use `node.text()` instead of `node.text` to retrieve the text content of the node.
AttributeError: 'NoneType' object has no attribute 'text'
The `css_first()` method (or similar node selection methods) returned `None` because no element matched the CSS selector, and a subsequent operation was attempted on this `None` object.
fix
Always check if the result of a node selection method is not `None` before attempting to access its attributes or methods, e.g., `node = tree.css_first('selector')
if node: print(node.text())`
Upgrade
Version history
0.4.11latest on PyPI · released Jul 15, 2026
Audit
Dependencies
pythonrequiredRequired Python version range.
CythonoptionalMay be needed for successful compilation during installation if `pip install selectolax` fails, especially with older selectolax versions on newer Python.
Agent activity
9 hits · last 30 days
node
6
Resources