Install & Compatibility
Where this runs
tested against v1.5.1 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.010s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.010s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tinycss2'
The tinycss2 library is not installed in your current Python environment.
fixInstall the tinycss2 package using pip: `pip install tinycss2`
TypeError: argument must be a string or bytes, not <class 'int'>
Parsing functions like `tinycss2.parse_stylesheet()` expect a string or bytes object as input, but received an incompatible type.
fixEnsure 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; }'`. AttributeError: 'list' object has no attribute 'type'
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`.
fixIterate over the returned list to access attributes of individual tokens: `for token in tinycss2.parse_stylesheet(css_string): print(token.type)`
ImportError: cannot import name 'parse_stylesheet_string' from 'tinycss2'
The function name `parse_stylesheet_string` does not exist in the `tinycss2` module; the correct function for parsing a CSS string is `parse_stylesheet`.
fixUse the correct import and function name: `from tinycss2 import parse_stylesheet`
Upgrade
Version history
1.5.1latest on PyPI · released Nov 23, 2025
Audit
Dependencies
webencodingsrequiredCharacter encoding aliases for legacy web content.