cssselect

library1.5.0pypypi✓ verified 30d ago

cssselect is a BSD-licensed Python library that parses CSS3 Selectors and translates them into XPath 1.0 expressions. These XPath expressions can then be used with an XPath engine like lxml to find matching elements in XML or HTML documents. The library is currently at version 1.4.0 and maintains an active development cycle with releases published on PyPI.

serialization

pip install cssselect

github ↗package ↗

INSTALL

IMPORT

SIG · CSSSELECT

cssselect

serializationpythonv1.5.0

Install

1.5s avg

Import

30ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.0 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.032s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.028s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

GenericTranslator

✓ from cssselect import GenericTranslator

HTMLTranslator

✓ from cssselect import HTMLTranslator

SelectorError

✓ from cssselect import SelectorError

css_to_xpath

✓ from cssselect import css_to_xpath

✗ from cssselect.xpath import css_to_xpath

The `css_to_xpath` function is directly available from the top-level `cssselect` package.

SelectorSyntaxError

✓ from cssselect import SelectorSyntaxError

This quickstart demonstrates how to use `cssselect` to translate a CSS selector into an XPath 1.0 expression and then apply it to an HTML document using `lxml` to find matching elements. It highlights the use of `HTMLTranslator` for HTML-specific translations.

from lxml.etree import fromstring from cssselect import HTMLTranslator, SelectorError html_doc = ''' <div id="outer"> <p class="content"> <span>Text 1</span> </p> <div id="inner" class="content body"> Text 2 <span>Text 3</span> </div> </div> ''' try: # Use HTMLTranslator for HTML documents for better pseudo-class handling translator = HTMLTranslator() xpath_expression = translator.css_to_xpath('div.content > span') print(f"Generated XPath: {xpath_expression}") document = fromstring(html_doc) # Find all elements matching the XPath expression matches = document.xpath(xpath_expression) for element in matches: print(f"Matched element tag: {element.tag}, text: {element.text.strip() if element.text else ''}") except SelectorError as e: print(f"Invalid CSS selector: {e}")

Debug

Known issues

breakingVersion 1.2.0 (released 2022-10-27) dropped support for Python 2.7, 3.4, 3.5, and 3.6. Ensure your environment uses Python 3.7 or newer.

fix

Upgrade Python to version 3.7 or higher.

affects: >=1.2.0

breakingBetween versions 0.9 and 0.9.1, the `selector_to_xpath()` function's default behavior for `translate_pseudo_elements` changed. In 0.9.1+, it defaults to `False` (ignoring pseudo-elements), reverting an accidental change in 0.9 which defaulted to `True` (rejecting them). When using `selector_to_xpath()` directly, explicitly set `translate_pseudo_elements=True` if you need pseudo-element support. `css_to_xpath()` is unaffected.

fix

For `selector_to_xpath()`, explicitly pass `translate_pseudo_elements=True` if you rely on pseudo-element translation, or `False` to ignore them. Consider using `css_to_xpath()` if pseudo-element behavior is critical and you want consistent default handling.

affects: 0.9.x

gotchaThe customization API, allowing subclassing of `GenericTranslator` or `HTMLTranslator` to override methods, is not considered stable. Its signature or behavior might change in future versions, potentially breaking your custom subclasses.

fix

Be aware that custom translator subclasses may require updates with new `cssselect` releases. Review the changelog and source code for any changes to the translation API.

affects: All versions

gotchaXPath 1.0, which `cssselect` translates to, does not natively support pseudo-elements (e.g., `::before`, `::after`). While `cssselect`'s `css_to_xpath()` provides some translation, `selector_to_xpath()` explicitly ignores them by default. This can lead to unexpected results if pseudo-elements are part of your CSS selectors.

fix

Avoid pseudo-elements in selectors intended for XPath 1.0, or be aware of their limited/non-existent translation. If using `selector_to_xpath()`, set `translate_pseudo_elements=True` to attempt translation, but be mindful of XPath 1.0 limitations.

affects: All versions

breakingThe `lxml` library is a required dependency for `cssselect`. If `lxml` is not installed in your Python environment, importing or using `cssselect` will result in a `ModuleNotFoundError`.

fix

Ensure `lxml` is installed in your Python environment. Typically, `pip install cssselect` should also install `lxml`. If you are installing dependencies manually or in a constrained environment, ensure `pip install lxml` is executed. Note that `lxml` requires compilation tools and development headers on some systems.

affects: All versions

gotchaThe `cssselect` library is frequently used in conjunction with other parsing libraries like `lxml` for HTML/XML processing. If your application or test script uses `lxml` (e.g., for parsing documents), ensure it is explicitly installed. `cssselect` does not list `lxml` as a direct dependency.

fix

Install `lxml` in your environment using `pip install lxml` if your project requires it alongside `cssselect`.

affects: All versions

Errors

Common errors & fixes

ImportError: cssselect seems not to be installed.

The cssselect library, although historically integrated with lxml, is now an independent package and needs to be installed separately for lxml's CSS selector functionality to work.

fix

pip install cssselect

AttributeError: 'lxml.etree._Element' object has no attribute 'cssselect'

This error occurs when attempting to use the .cssselect() method on an lxml element without the cssselect package being properly installed in the Python environment.

fix

pip install cssselect

cssselect.parser.SelectorSyntaxError: Expected selector, got <DELIM '(' at ...>

The CSS selector string provided contains a syntax error, such as unescaped special characters (e.g., parentheses, colons) in class names or malformed selector patterns, which prevents cssselect from parsing it correctly.

fix

Review the CSS selector for syntax validity, ensuring proper escaping of special characters (e.g., `\` for colons or periods in names, or quoting attribute values with spaces) and correct adherence to CSS selector grammar.

cssselect.xpath.ExpressionError: Unknown or unsupported selector (eg. pseudo-class)

The CSS selector uses a pseudo-class, pseudo-element, or other advanced feature that cssselect cannot translate into a valid XPath 1.0 expression because XPath 1.0 has limitations compared to modern CSS selectors.

fix

Simplify the CSS selector to use only features supported by cssselect and XPath 1.0, or consider using direct XPath expressions for complex selections.

Upgrade

Version history

1.5.0latest on PyPI · released Jul 27, 2026

Audit

Dependencies

lxmloptionalWhile cssselect generates XPath independently, lxml is the primary library used to execute the generated XPath expressions against HTML/XML documents. Its test suite also requires lxml.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/scrapy/cssselect ↗

packagehttps://pypi.org/project/cssselect/ ↗