NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #105 most downloaded on PyPI
A modern CSS selector implementation for Beautiful Soup.
Latest stable
4.1.3
Last release 2 days ago
20 Nov 2026
Release timing varies
gaps range from 2 weeks to 4 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
2 versions withdrawn
withdrawn after publishing
8 years old
67 releases · first in 2018
Drag across the ruler to compare, or tap a release to open it.
FIX : Fix filter() given a list of tags taking time and memory quadratic in the number of top level elements of a document, such as a fragment parsed
filter() given a list of tags taking time and memory quadratic in the number of top level elementshtml.parser, for selectors that count siblings, like:nth-child() or :first-of-type. The tags were grouped by their top level element, so each top level elementselect().of-type selectors, such as :first-of-type, :last-of-type, :only-of-type, and:nth-of-type(), taking time quadratic in the number of siblings when many of them have distinct tag names, as:lang() stops checking a language against its list of values at the first value that matches. Along withmax_selectors does not limit the length of selector strings, or the number of values inYour coding agent can read these notes before it upgrades. Set up the MCP server →
FIX : Fix :lang() taking time quadratic in the number of top level elements of a fragment that have an html or head child, such as many documents conc
:lang() taking time quadratic in the number of top level elements of a fragment that have an htmlhead child, such as many documents concatenated and parsed with html.parser, as the content language:lang() taking time quadratic in the size of the document when many elements share a long language<html lang>, as the tag was checked and matched again for every element.:-soup-contains() taking time quadratic in the depth of the document, such as a long list of<li> parsed with html.parser, as the text of every element, which includes that of all itsNOCACHE now turns off the caches of the content language in a document's header, of the forms of aselect, so :lang(), :default, :indeterminate and :checkediselect().nth selectors with very large An+B values raising an OverflowError when matching, andSelectorSyntaxError instead of a ValueError.filter() given a list of tags now matches the tags under the same top level element together, sharing:scope or & still matches each tagignore option now disallows a pseudo-class however its name is written, as names were compared:h\61 s(), was not disallowed. Document:contains() for :-soup-contains(), must be listed as well.FIX : Improve performance of tag name matching, which runs for every element and selector.
nth selectors taking polynomial time when nested inside the of S of other nth selectors, such:nth-last-child(n of :nth-last-child(n of li)), as each level of nesting multiplied the work by the numbernth selectors inside :has() with a subsequent-sibling combinator, such as:has(~ :nth-child(n of li)), were also quadratic. Each sibling is now evaluated against an nth selector at mostrange input's value is clamped to its minimum and maximum, 0 and 100 by default, so it now matches:out-of-range only when its maximum is less than its minimum, and :in-range otherwise, including without minmax. A range input that is disabled, readonly or in a datalist matches neither.:in-range and :out-of-range no longer match an input of any type that is disabled, readonly or in adatalist, as it is barred from constraint validation.:in-range and :out-of-range treat a date, month, week or datetime-local value after:placeholder-shown sanitizes an input's value before checking it, as browsers do, so it matches when theurl and email, or, for number, not a valid floating-point1e9999.:placeholder-shown taking time quadratic in the depth of the document, as it got the text of everytextarea.NEW : Soup Sieve is now thread safe, and this is now tested, including on free-threaded Python. This is assuming read only operations on a document. C
/* comment */ div, failing[attr=value], [attr$=value], [attr|=value], and [attr!=value] ignoring a trailing newline in[type=hidden] no longer matches type="hidden ".contenteditable state, the select of an option, and the tree that an element:lang(), :read-write, :read-only, :checked, :default,:indeterminate to avoid quadratic time on deeply nested documents.:lang('') not matching every element without any language information, which per the HTML spec hashead.:lang() no longer matches an element whose language tag is not well-formed BCP 47 syntax, such as -,en-, en_US, or a subtag longer than 8 characters, and a language range that is not well-formed matcheslang="-" matched :lang(''), and ill-formed tags matched :lang('*').:lang() ranges that end in a wildcard, such as en-* or *-*, never matching. As RFC 4647 extendeden-* matches the same as en.[attr*=value] and [attr$=value] taking time quadratic in the length of the value when it nearlyFIX : Cache whether an element is or has a matching descendant when matching :has() to avoid quadratic time on deeply nested documents.
:has() to avoid quadratic timea > b) so it is matched once fordiv:has(> p) > span.BREAK : The contents of an HTML template are no longer treated as part of the document. Selectors do not descend into a template , and elements inside
template are no longer treated as part of the document. Selectors do nottemplate, and elements inside one can't see beyond it, which also applies to pseudo-classes such:lang(), :disabled, and :default. select and filter will still reach the contents of a template whentemplate itself, for example soup.template.select('p'). See theiframe are no longer treated as a separate document, as they are not one in aiframe are normal children, so :root does not match them, and :default,:indeterminate, :checked, :dir(), :lang(), and :read-write treat them like any other element. Recenthtml.parser, lxml, and html5lib all escape the contents of an iframe like a browser does, sohtml.parser,iframe by hand. :-soup-contains() now also includes the escaped text in an iframe.:disabled and :enabled to treat option and optgroup elements inside a disabled select as:has(~ ...) never matching top level elements of a fragment:indeterminate now treats a radio button group without a form as extending across the whole document:default to treat a button with a missing or invalid type, and an input with type="image",:in-range and :out-of-range raising TypeError when the document contains an input without atype attribute.:read-write (and :read-only) now treat contenteditable="plaintext-only" elements as editing hosts andcontenteditable state.:read-write (and :read-only) now ignore contenteditable on non-HTML elements, such as an SVGforeignObject, as the attribute only applies to HTML elements. Such elements inherit the state of their parent.:checked now only matches the last radio button with a checked attribute in a radio button group, asname and form, including the form attribute.:default still matches all of them, and the contents of a template are unaffected as they are not connected.:dir() and :defined no longer affect the rest of the selector list they are in. Previously, a selectoriframe, ignored the specified namespaces,:not(:dir(ltr)) and :not(:defined) now do.:default and :indeterminate now honor the form attribute, which can associate a submit button ortemplate, as in the HTML:default, :checked, and :indeterminate now handle a form inside a form like a browser. In HTML, ahtml.parser. In XHTML and in a template, nested forms are real forms.:checked now matches the option that a browser would select. Without multiple, that is only theoption with a selected attribute in a select, and if there are none and the select shows a singleoption that is not disabled. :default still only considers the selected attribute.[attribute!=value] excluding values that only start with the specified value, and in XML documents,type values that contain a newline.rel,method, lang, dir, ...) without ASCII case sensitivity on HTML elements in HTML documents, not just type.:dir() now matches non-HTML elements, such as SVG and MathML, by the direction they inherit from theirdir attribute only applies to HTML elements), and HTML elements inside them, such as in an SVGforeignObject, by the direction of their ancestors.:dir() ignoring the value of an input with dir="auto" and a missing or empty type.:dir() now uses a table generated from Unicode 18 instead of unicodedata, so results no longer depend:dir() now uses the value of an input with dir="auto" when type is hidden, password, submit,reset, or button, as the HTML specification does.dir="auto" and bdi now analyze the text of non-HTML elements, such as SVG and MathML, and only ignorescript, style, and bdi. The text directly in an iframe is analyzed as well, and thetemplate, which are not part of the document, are not.:dir() no longer lets the contents of a template inherit direction from the template or its:dir() now matches a bdi element that is the root by its text instead of assuming left to right.:dir() now treats any element without a parent element as left to right, not just the root. Before,html.parser never matched.:dir() now accepts any identifier, as CSS requires, including escaped ones. Values other than ltr andrtl do not match anything.svg elementhtml5lib document. Previously every element in such a tree was treated as an HTML element,:lang() treating an element with an empty lang or xml:lang attribute as having the language of:default to avoid quadratic time on forms with:in-range and :out-of-range matching elements whose value, min, or max has a trailing newline;:in-range and :out-of-range raising ValueError when a date, month, week, or local date andinput has a year with more digits than Python will convert; such a year is now treated as invalid.:in-range and :out-of-range not recognizing a datetime-local value, min, or max that uses aT to separate the date and time.:indeterminate to avoid quadratic time:lang() now uses the lang attribute of SVG elements, as the HTML specification does (with xml:langxml:lang was considered for elements outside the HTML namespace.:defined no longer matches HTML elements with an is attribute (customized built-in elements), which,a ~ b and :has(~ b)) toi modifier using ASCII case insensitivity.input with an unknown type, such as type="foo", as a text input in :placeholder-shown,:read-write, :read-only and :dir(), as an invalid type is in the Text state in the HTML specification.:enabled and :disabled never matching input elements with type="hidden".:required no longer matches input elements of types the required attribute does not apply tohidden, range, color, submit, image, reset and button). Like in browsers, they match :optional.a b) toFIX : Keep own and descendant text separate when combining :-soup-contains() and :-soup-contains-own() .
:-soup-contains() and :-soup-contains-own().:dir() to avoid quadratic time on deeply nesteddir="auto" elements.auto handling in regard to :dir() selector. When an element with dir="auto" (or a <bdi>):in-range and :out-of-range raising ValueError for week inputs whose week-year is 10000 or:nth-last-child(an+b of S) matching the wrong elements when the first sibling tested does notS.escape() now only leaves non-ASCII identifier code points unescaped, as defined by the CSS specification.:in-range and :out-of-range treating time and datetime-local values with seconds asFIX : When matching with > , the BeautifulSoup object should not count as a parent.
>, the BeautifulSoup object should not count as a parent.:has(~) would incorrectly match a sibling that came beforeFIX : Python versions less than 3.11.5 have broken possessive quantifiers, so require at least 3.11.5 for Soup Sieve 3.0+. 3.0 and 3.0.1 will be yanke
FIX : Fix regression related to [attribute!=value] where previously it would match if the attribute was not present and recent changes broke that. Ess
[attribute!=value] where previously it would match if the attribute was not[attribute!=value] should be the same as:not([attribute=value]).BREAK : :has() , by default, now behaves according to CSS more strictly, disallowing complex selectors that use combinators and prevents nesting :has(
:has(), by default, now behaves according to CSS more strictly, disallowing complex selectors that use:has() within :has(). This gives a safer, more performant default for SoupNOSTRICT flag restoringmy_selectors = soupsive.CustomSelectors({custm: selector, ...}).max_selectors that can be used to control the maximum allowed selectors in a givenU+FFFD. (#307)NEW : Add new ignore option to API methods that allows the specification of specific pseudo-classes to be ignored.
ignore option to API methods that allows the specification of specific pseudo-classes to benamespaces and custom objects must always be a Mapping, previously listsNull of type SelectorNull.NOCACHE flag that can be used to disable caching optimizations selectors and possibly other future~ for various cases by employing caching.nth-* family of selectors in certain scenarios by employing caching.custom is properly passed down from API functions to compilation.FIX: Fix issue where :is() and :where() were not accounting for empty selectors in the max selector count as they should (@arpitjain099).
:is() and :where() were not accounting for empty selectors in the max selector count as
they should (@arpitjain099).:has() was allowing empty selectors in some circumstances even though it is not
forgiving.:is() and :where() contain empty selectors.FIX: Correct [attr^=""], [attr$=""], and [attr*=""] to match nothing when the value is empty, per CSS Selectors Level 4 substring matching, which prev
[attr^=""], [attr$=""], and [attr*=""] to match nothing when the value is empty, per CSS
Selectors Level 4 substring matching, which previously matched any element merely having the attribute
(@chuenchen309).NEW: Lazy compile selector patterns to improve initial import speed.
:nth-child/:nth-of-type (and -last- variants) for An+B values whose sequence steps onto
index 0 or onto the last child (e.g. :nth-child(2n-2), :nth-child(n-1), :nth-child(n+5)), which previously
matched the wrong elements or nothing at all (@gaoflow).FIX: Fix another inefficient attribute pattern (@mauriceng98).
FIX: Fix inefficient attribute pattern.
FIX: Ensure custom selectors or namespace dictionaries reject non-string keys (@mundanevision20).
:in-range and :out-of-range with end of year weeks (@mundanevision20).FIX: Changes in tests to accommodate latest Python HTML parser changes.
NEW: Drop support for Python 3.8.
NEW: Add :open pseudo selector.
:open pseudo selector.:muted pseudo selector.:autofill, :buffering, :fullscreen, :picture-in-picture,
:popover-open, :seeking, :stalled, and :volume-locked. These selectors, while recognized, will not match any
element as they require a live environment to check element states and browser states. This just prevents Soup Sieve
from failing when any of these selectors are specified.NEW: Add official support for Python 3.13.
& as scoping root per the CSS Nesting Module, Level 1. When & is used outside the
context of nesting, it is treated as the scoping root (equivalent to :scope).NEW: Update to support Python 3.12.
FIX: Attribute syntax for case insensitive flag optionally allows a space, it does not require one.
NEW: Update to support changes related to :lang() in the official CSS spec. :lang("") should match unspecified languages, e.g. lang="", but not lang=u
:lang() in the official CSS spec. :lang("") should match unspecified
languages, e.g. lang="", but not lang=und.:is() and :where() should allow forgiving selector lists according to latest CSS (as far as Soup
Sieve supports "forgiving" which is limited to empty selectors).FIX: Documentation for installation from source is outdated.
FIX: Fix some typos in error messages.
FIX: Ensure attribute selectors match tags that have new lines characters in attributes.
NEW: Officially support Python 3.10.
:has(), :is(), and :where() now use use a forgiving selector list. While not as forgiving as CSS might
be, it will forgive such things as empty sets and empty slots due to multiple consecutive commas, leading commas, or
trailing commas. Essentially, these pseudo-classes will match all non-empty selectors and ignore empty ones. As the
scraping environment is different than a browser environment, it was chosen not to aggressively forgive bad syntax and
invalid features to ensure the user is alerted that their program may not perform as expected.SelectorList for debug purposes.FIX: Fix an issue with namespaces when one of the keys is self.
self.NEW: :link and :any-link no longer include due to a change in the level 4 selector specification. This actually yields more sane results.
:link and :any-link no longer include <link> due to a change in the level 4 selector specification. This actually yields more sane results.find, is quite forgiving of odd types that a user may place in an element's attribute value. Soup Sieve will also now be more forgiving and attempt to match these unexpected values in a sane manner by normalizing them before compare. (#212)As a consequence, :contains() will now be known as :-soup-contains(), though for a time the deprecated form of :contains() will still be allowed with…
:-soup- prefix. As a consequence, :contains() will now be known as :-soup-contains(), though for a time the deprecated form of :contains() will still be allowed with a warning that users should migrate over to :-soup-contains().:-soup-contains-own() which operates similar to :-soup-contains() except that it only looks at text nodes directly associated with the currently scoped element and not its descendants.bs4 globally instead of in local functions as it appears there are no adverse affects due to
circular imports as bs4 does not immediately reference soupsieve functions and soupsieve does not immediately reference bs4 functions. This should give a performance boost to functions that had previously included bs4 locally.## 2.0.1 - FIX: Remove unused code.
NEW: Remove deprecated comments and icomments from the API.
SelectorSyntaxError is derived from Exception not SyntaxError.comments and icomments from the API.|.Note: Last version for Python 2.7
Note: Last version for Python 2.7
|.FIX: :placeholder-shown should not match if the element has content that overrides the placeholder.
:placeholder-shown should not match if the element has content that overrides the placeholder.FIX: :checked rule was too strict with option elements. The specification for :checked does not require an option element to be under a select element
:checked rule was too strict with option elements. The specification for :checked does not require an
option element to be under a select element.:lang() wildcard match handling with singletons. Implicit wildcard matching should not
match any singleton. Explicit wildcard matching (* in the language range: *-US) is allowed to match singletons.FIX: [attr!=value] pattern was mistakenly using :not([attr|=value]) logic instead of :not([attr=value]).
[attr!=value] pattern was mistakenly using :not([attr|=value]) logic instead of :not([attr=value])._QUIRKS mode flag. Beautiful Soup was meant to use it to help with transition to Soup Sieve, but never released with it. Help with transition at this point is no longer needed.FIX: Shortcut last descendant calculation if possible for performance.
Doctype strings can be mistaken for a normal text node in some cases.:root tag if it has sibling text nodes or tag nodes. This is an issue that mostly manifests when using html.parser as the parser will allow multiple root nodes.FIX: :root, :contains(), :default, :indeterminate, :lang(), and :dir() will properly account for HTML iframe elements in their logic when selecting or
:root, :contains(), :default, :indeterminate, :lang(), and :dir() will properly account for HTML iframe elements in their logic when selecting or matching an element. Their logic will be restricted to the document for which the element under consideration applies.NEW: Deprecate comments and icomments functions in the API to ensure Soup Sieve focuses only in CSS selectors. comments and icomments will most likely…
:contains() to accept a list of text to search for. (#115)escape function for escaping CSS identifiers. (#125)comments and icomments functions in the API to ensure Soup Sieve focuses only in CSS selectors. comments and icomments will most likely be removed in 2.0. (#130)soupsieve package. (#111):contains() comparison.U+FFFD) according to the specification. This applies to CSS escaped NULL characters as well. (#124)U+FFFD outside of CSS strings. In a string, they should just be ignored, but as there is no case where we could resolve such a string and still have a valid selector, string handling remains the same. (#128)NEW: Add custom selector support.
-. (#107)\r\n as a single character, especially in cases such as string escapes: \\\r\n. (#107)-- as a valid identifier or identifier start. (#107)SelectorSyntaxError, which is still currently derived from SyntaxError, but will most likely be derived from Exception in the future.FIX: Fix regression with tag names in regards to case sensitivity, and ensure there are tests to prevent breakage in the future.
FIX: Fix HTML detection for type selector.
type selector.:enabled and :disabled.FIX: Fix issue with :has() selector where a leading combinator can only be provided in the first selector in a relative selector list.
:has() selector where a leading combinator can only be provided in the first selector in a relative selector list.NEW: Add support for :in-range and :out-of-range selectors.
:in-range and :out-of-range selectors. (#60):defined selector. (#76)NullSelector object. (#70):nth-* patterns were converting numbers to base 16 when they should have been converting to base 10.FIX: Fix pattern compile issues on Python < 2.7.4.
\d in Unicode Re patterns as they will contain characters outside the range of [0-9].FIX: Fix warning about not importing Mapping from collections.abc.
Mapping from collections.abc.NEW: Add closest method to the API that matches closest ancestor.
closest method to the API that matches closest ancestor.select_one reference to module's __all__.NEW: Add select_one method like Beautiful Soup has.
select_one method like Beautiful Soup has.:dir() selector (HTML only).BeautifulSoup object as a parent).nth range check.select_one method like Beautiful Soup has.:dir() selector (HTML only).BeautifulSoup object as a parent).nth range check.NEW: Throw NotImplementedError for at-rules: @page, etc.
NotImplementedError for at-rules: @page, etc.:host, :host(), and :host-context().:read-write and :read-only.\r, \n, and \f cannot be escaped with \ in CSS. You must use Unicode escapes.FIX: Fix issue with undefined namespaces.
NEW: :user-invalid, :playing, :paused, and :local-link will not cause a failure, but all will match nothing as their use cases are not possible in an
:scope.:user-invalid, :playing, :paused, and :local-link will not cause a failure, but all will match nothing as their use cases are not possible in an environment outside a web browser.[attr~=value] handling of whitespace. According to the spec, if the value contains whitespace, or is an empty string, it should not match anything.FIX: More descriptive exceptions. Exceptions will also now mention position in the pattern that is problematic.
filter ignores NavigableString objects in normal iterables and Tag iterables. Basically, it filters all Beautiful Soup document parts regardless of iterable type where as it used to only filter out a NavigableString in a Tag object. This is viewed as fixing an inconsistency.DEBUG flag has been added to help with debugging CSS selector parsing. This is mainly for development.meta tag, and no language is found, cache that there is no language in the meta tag to prevent searching again during the current select.BeautifulSoup/Tag object is given to the API to compare against, raise a TypeError.NEW: Remove old pre 1.0 deprecations.
NEW: Adds support for [attr!=value] which is equivalent to :not([attr=value]).
[attr!=value] which is equivalent to :not([attr=value]).:active, :focus, :hover, :visited, :target, :focus-within, :focus-visible, :target-within, :current()/:current, :past, and :future, but they will never match as these states don't exist in the Soup Sieve environment.:checked, :enabled, :disabled, :required, :optional, :default, and :placeholder-shown which will only match in HTML documents as these concepts are not defined in XML.:link and :any-link, both of which will target all <a>, <area>, and <link> elements with an href attribute as all links will be treated as unvisited in Soup Sieve.:lang() (CSS4) which works in XML and HTML.prefix:attr can be matched with the form [prefix\:attr] without specifying a namespaces if desired.[type] is used (with no value).FIX: Use proper CSS identifier patterns for tag names, classes, ids, etc. Things like #3 or #-3 should not match and should require #\33 or #-\33.
#3 or #-3 should not match and should require #\33 or #-\33.NotImplementedError for supported pseudo classes/elements with bad syntax, instead raise SyntaxError.FIX: When giving a tag to select, it should only return the children of that tag, never the tag itself.
select, it should only return the children of that tag, never the tag itself.NotImplementedError when an unsupported pseudo class is used.## 1.0.0 - NEW: Official 1.0.0 release.
NEW: Drop document flags. Document type can be detected from the Beautiful Soup object directly.
:contains and child considerations for :empty.One column per quarter.