Join us in Long Beach, CA starting May 13, 2026. Grab your ticket and discounted hotel today before they’re gone!  REGISTER FOR PYCON US!

A fast HTML5 parser with CSS selectors, written in Cython, using Modest and Lexbor engines.

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for rushter from gravatar.com rushter

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License Expression: MIT
    SPDX License Expression
  • Author: Artem Golubin
  • Tags selectolax , html , parser , css , fast , lexbor , modest
  • Requires: Python <3.15, >=3.9
  • Provides-Extra: cython
Classifiers
Report project as malware

Project description

A fast HTML5 parser with CSS selectors, written in Cython, using Modest and Lexbor engines.

PyPI - Version PyPI Total Downloads CI Python Versions GitHub License

Installation

From PyPI using pip:

pip install selectolax

If installation fails due to compilation errors, you may need to install Cython:

pip install selectolax[cython]

This usually happens when you try to install an outdated version of selectolax on a newer version of Python.

Development version from GitHub:

git clone --recursive  https://github.com/rushter/selectolax
cd selectolax
pip install -r requirements_dev.txt
python setup.py install

How to compile selectolax while developing:

make clean
make dev

Basic examples

Here are some basic examples to get you started with selectolax:

Parsing HTML and extracting text:

In [1]: from selectolax.lexbor import LexborHTMLParser
   ...:
   ...: html = """
   ...: <h1 id="title" data-updated="20201101">Hi there</h1>
   ...: <div class="post">Lorem Ipsum is simply dummy text of the printing and typesetting industry. </div>
   ...: <div class="post">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</div>
   ...: """
   ...: tree = LexborHTMLParser(html)

In [2]: tree.css_first('h1#title').text()
Out[2]: 'Hi there'

In [3]: tree.css_first('h1#title').attributes
Out[3]: {'id': 'title', 'data-updated': '20201101'}

In [4]: [node.text() for node in tree.css('.post')]
Out[4]:
['Lorem Ipsum is simply dummy text of the printing and typesetting industry. ',
 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.']

Using advanced CSS selectors

In [1]: html = "<div><p id=p1><p id=p2><p id=p3><a>link</a><p id=p4><p id=p5>text<p id=p6></div>"
   ...: selector = "div > :nth-child(2n+1):not(:has(a))"

In [2]: for node in LexborHTMLParser(html).css(selector):
   ...:     print(node.attributes, node.text(), node.tag)
   ...:     print(node.parent.tag)
   ...:     print(node.html)
   ...:
{'id': 'p1'}  p
div
<p id="p1"></p>
{'id': 'p5'} text p
div
<p id="p5">text</p>

Using lexbor-contains CSS pseudo-class to match text

from selectolax.lexbor import LexborHTMLParser
html = "<div><p>hello </p><p id='main'>lexbor is AwesOme</p></div>"
parser = LexborHTMLParser(html)
# Case-insensitive search
results = parser.css('p:lexbor-contains("awesome" i)')
# Case-sensitive search
results = parser.css('p:lexbor-contains("AwesOme")')
assert len(results) == 1
assert results[0].text() == "lexbor is AwesOme"

Available backends

Selectolax supports two backends: Modest and Lexbor. By default, all examples use the Lexbor backend. Most of the features between backends are almost identical, but there are some differences.

As of 2024, the preferred backend is Lexbor. The Modest backend is still available for compatibility reasons and the underlying C library that selectolax uses is not maintained anymore.

To use lexbor, just import the parser and use it in the similar way to the HTMLParser.

In [1]: from selectolax.lexbor import LexborHTMLParser

In [2]: html = """
   ...: <title>Hi there</title>
   ...: <div id="updated">2021-08-15</div>
   ...: """

In [3]: parser = LexborHTMLParser(html)
In [4]: parser.root.css_first("#updated").text()
Out[4]: '2021-08-15'

Simple Benchmark

  • Extract title, links, scripts and a meta tag from main pages of top 754 domains. See examples/benchmark.py for more information.
Package Time
Beautiful Soup (html.parser) 61.02 sec.
lxml / Beautiful Soup (lxml) 9.09 sec.
html5_parser 16.10 sec.
selectolax (Modest) 2.94 sec.
selectolax (Lexbor) 2.39 sec.

Links

License

Contributors

Thanks to all the contributors of selectolax!

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page