selectolax

0.4.7 · active · verified Thu Apr 09

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.

Warnings

breaking Empty 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.
deprecated The `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.
gotcha The `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: ...`.
gotcha Version `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.
gotcha Earlier 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.
gotcha Installation 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.

Install

pip install selectolax Standard installation
pip install selectolax[cython] Installation with Cython for compilation issues

Imports

LexborHTMLParser
```
from selectolax.lexbor import LexborHTMLParser
```
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.

Quickstart

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']})")

view raw JSON →