Tinycss2

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

tinycss2 is a low-level CSS parser and generator written in Python. It can parse CSS strings, return objects representing tokens and blocks, and generate CSS strings from these objects. Based on the CSS Syntax Level 3 specification, it handles the grammar of CSS but does not know specific rules, properties, or values. It is actively maintained with regular releases.

pip install tinycss2

Common errors

error ModuleNotFoundError: No module named 'tinycss2' ↓

cause The tinycss2 library is not installed in your current Python environment.

fix

Install the tinycss2 package using pip: pip install tinycss2

error TypeError: argument must be a string or bytes, not <class 'int'> ↓

cause Parsing functions like `tinycss2.parse_stylesheet()` expect a string or bytes object as input, but received an incompatible type.

fix

Ensure the input to the parsing function is a str (for parse_stylesheet) or bytes (for parse_stylesheet_bytes) object. For example, css_string = '.selector { color: red; }'.

error AttributeError: 'list' object has no attribute 'type' ↓

cause The `tinycss2.parse_stylesheet()` function returns a list of tokens, not a single token object, so you must iterate over the list to access individual token attributes like `type` or `value`.

fix

Iterate over the returned list to access attributes of individual tokens: for token in tinycss2.parse_stylesheet(css_string): print(token.type)

error ImportError: cannot import name 'parse_stylesheet_string' from 'tinycss2' ↓

cause The function name `parse_stylesheet_string` does not exist in the `tinycss2` module; the correct function for parsing a CSS string is `parse_stylesheet`.

fix

Use the correct import and function name: from tinycss2 import parse_stylesheet

Warnings

deprecated The `tinycss2.parse_declaration_list` function was deprecated in v1.3.0. ↓

fix Use `tinycss2.parse_blocks_contents` instead for parsing declaration lists.

breaking Python 3.6 support was dropped in v1.2.0, and Python 3.5 support in v1.1.0. The library currently requires Python 3.10 or newer. ↓

fix Ensure your project uses Python 3.10 or a more recent compatible version.

gotcha tinycss2 is a low-level CSS parser. It understands CSS syntax (tokens, blocks, qualified rules, at-rules) but does not interpret the semantics of specific CSS properties, values, or selectors. It does not provide high-level representations of browser-rendered styles. ↓

fix Users are expected to build their own higher-level logic on top of tinycss2's parsed output if they need to interpret CSS rules beyond their grammatical structure.

breaking In tinycss2 v0.5, the default behavior for parsing functions changed to preserve CSS comments and top-level whitespace in the output AST. Previously, these were skipped by default. ↓

fix If upgrading from very old versions and expecting comments/whitespace to be omitted, pass `skip_comments=True` and `skip_whitespace=True` to parsing functions like `parse_stylesheet` or `parse_declaration_list`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.01s 18.1M

3.10 alpine (musl) - - 0.01s 18.1M

3.10 slim (glibc) wheel 1.5s 0.01s 19M

3.10 slim (glibc) - - 0.01s 19M

3.11 alpine (musl) wheel - 0.01s 20.0M

3.11 alpine (musl) - - 0.01s 20.0M

3.11 slim (glibc) wheel 1.7s 0.01s 21M

3.11 slim (glibc) - - 0.01s 21M

3.12 alpine (musl) wheel - 0.01s 11.9M

3.12 alpine (musl) - - 0.01s 11.9M

3.12 slim (glibc) wheel 1.5s 0.01s 12M

3.12 slim (glibc) - - 0.01s 12M

3.13 alpine (musl) wheel - 0.01s 11.6M

3.13 alpine (musl) - - 0.01s 11.5M

3.13 slim (glibc) wheel 1.4s 0.01s 12M

3.13 slim (glibc) - - 0.01s 12M

3.9 alpine (musl) wheel - 0.01s 17.6M

3.9 alpine (musl) - - 0.01s 17.6M

3.9 slim (glibc) wheel 1.8s 0.01s 18M

3.9 slim (glibc) - - 0.01s 18M

Imports

parse_stylesheet

import tinycss2
rules = tinycss2.parse_stylesheet('body { color: red; }')

Primary function for parsing full CSS stylesheets.

ast nodes (e.g., QualifiedRule, IdentToken)
```
from tinycss2.ast import QualifiedRule, IdentToken
```
While often not directly imported, AST node classes reside in the `tinycss2.ast` module for inspection and manipulation of parsed output.

Quickstart stale last tested: 2026-04-23

Parses a CSS string into an Abstract Syntax Tree (AST) of tokens and blocks, then iterates through the parsed rules and declarations.

import tinycss2

css_input = '#my-id div { width: 50%; height: 100px }'
rules = tinycss2.parse_stylesheet(css_input)

# The parsed output is a list of nodes
for rule in rules:
    if rule.type == 'qualified-rule':
        print(f"Qualified Rule: {rule.prelude[0].value} {rule.prelude[2].value}") # Example: 'my-id', 'div'
        for declaration in tinycss2.parse_declaration_list(rule.content):
            if declaration.type == 'declaration':
                print(f"  Declaration: {declaration.name}: {declaration.value[0].value}{declaration.value[0].unit}")

# To serialize back to CSS (approximate)
serialized_css = ''.join(node.serialize() for node in rules)
print(f"\nSerialized CSS: {serialized_css}")