SoupSieve: A Modern CSS Selector Implementation for Beautiful Soup

2.8.3 verified Tue May 12 auth: no python install: stale quickstart: stale

SoupSieve is a modern CSS selector implementation for Beautiful Soup, currently at version 2.8.3. It is actively maintained and follows a regular release cadence, with recent updates addressing various fixes and improvements.

pip install soupsieve

Common errors

error ModuleNotFoundError: No module named 'soupsieve' ↓

cause The 'soupsieve' library is not installed in the current Python environment. It is a dependency for `beautifulsoup4`'s CSS selector features.

fix

Install soupsieve using pip: pip install soupsieve (or pip install beautifulsoup4 which includes it as a dependency).

error ImportError: cannot import name 'select' from 'soupsieve' ↓

cause Users are attempting to directly import the `select` function (or other internal components) from the `soupsieve` library, which is not exposed for public use. `soupsieve` is an internal dependency of `beautifulsoup4`.

fix

Instead of importing, use the select() method directly on a BeautifulSoup object, e.g., soup.select('css_selector').

error soupsieve.util.SelectorSyntaxError: Malformed attribute selector ↓

cause The CSS selector string provided to `BeautifulSoup.select()` (which uses `soupsieve` internally) contains incorrect or invalid syntax, specifically a malformed attribute selector.

fix

Review and correct the CSS selector string to conform to valid CSS selector syntax (e.g., [attr="value"] instead of [attr=value]).

Warnings

breaking SoupSieve 2.8 drops support for Python 3.8 and earlier versions. ↓

fix Upgrade your Python environment to version 3.9 or later to ensure compatibility.

deprecated The ':in-range' and ':out-of-range' pseudo-classes are deprecated in SoupSieve 2.8. ↓

fix Avoid using ':in-range' and ':out-of-range' pseudo-classes in your CSS selectors.

breaking The `soupsieve` library requires `beautifulsoup4` as a dependency. `ModuleNotFoundError: No module named 'bs4'` indicates that `beautifulsoup4` is not installed in the environment. ↓

fix Ensure `beautifulsoup4` is installed. You can install it using `pip install beautifulsoup4`.

breaking SoupSieve requires Beautiful Soup 4 ('bs4') as a dependency. The module 'bs4' was not found. ↓

fix Install the 'beautifulsoup4' package using 'pip install beautifulsoup4'.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

SoupSieve
```
from soupsieve import SoupSieve
```
Ensure you import SoupSieve directly from the 'soupsieve' package to access its functionalities.

Quickstart stale last tested: 2026-04-23

A simple example demonstrating how to use SoupSieve to parse HTML and select elements using CSS selectors.

from soupsieve import SoupSieve

# Example usage of SoupSieve
html = '<html><body><div class="content">Hello, World!</div></body></html>'
soup = SoupSieve(html)
elements = soup.select('.content')
print(elements[0].text)  # Output: Hello, World!