css-inline

library0.21.2pypypi✓ verified 24d ago

css-inline is a high-performance Python library (version 0.20.2) for inlining CSS into HTML 'style' attributes. Built on components from Mozilla's Servo project, it is significantly faster than other alternatives and is primarily designed for use cases such as preparing HTML emails or embedding HTML into third-party web pages where inline styles are a requirement. It's actively maintained with regular releases.

communication web-framework serialization devops

pip install css-inline

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CSS-INLINE

css-inline

communicationpythonv0.21.2

Install

1.6s avg

Import

33ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.21.2 · 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.038s · 22.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.028s · 23MB

20MB installed

● package 20MB

Code

Verified usage

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

inline

✓ from css_inline import inline

inline_many

✓ from css_inline import inline_many

For processing multiple documents concurrently for performance benefits.

CSSInliner

✓ from css_inline import CSSInliner

For custom configuration and reusing options across multiple inlining calls.

This example demonstrates basic CSS inlining, showing how styles from a <style> tag are applied to elements. It also illustrates how to use `keep_at_rules` and `keep_style_tags` options to prevent the default removal of `@media` queries and the original style tags.

from css_inline import inline html_content = """ <html> <head> <style> h1 { color: blue; } p { font-size: 14px; margin-bottom: 5px; } .highlight { background-color: yellow; } @media screen and (max-width: 600px) { p { color: #555; } } </style> </head> <body> <h1 class="highlight">Hello, World!</h1> <p>This is a paragraph.</p> <p style="color: green;">This paragraph has an existing inline style.</p> </body> </html> """ inlined_html = inline(html_content, keep_at_rules=True, keep_style_tags=True) print(inlined_html)

Debug

Known issues

gotchaBy default, `<style>` and `<link>` tags (including their contents) are removed from the resulting HTML after inlining. If you need to preserve them (e.g., for responsive email media queries), use the `keep_style_tags=True` or `keep_link_tags=True` options.

fix

Pass `keep_style_tags=True` and/or `keep_link_tags=True` to the `inline()` function or `CSSInliner` constructor.

affects: All versions

gotchaAt-rules (like `@media`, `@font-face`) cannot be inlined into `style` attributes and are removed by default. To preserve them (e.g., for responsive email layouts), set `keep_at_rules=True`.

fix

Pass `keep_at_rules=True` to the `inline()` function or `CSSInliner` constructor. Note that preserved `@rules` will remain in `<style>` tags if `keep_style_tags` is also `True`.

affects: All versions

gotchaWhen inlining HTML fragments, `css-inline` automatically adds missing `<html>` and `<body>` tags to ensure the output is a valid HTML document. If you specifically need to process and return only the contents of an HTML fragment without these structural tags, consider processing and then manually stripping them, or use `inline_many_fragments` which might offer more control.

fix

Be aware of this behavior for fragments. If strict fragment output is needed, post-process the output or use specialized methods if available for fragments.

affects: All versions

breakingThe `inline_with_options` and `inline_many_with_options` functions were removed. Users should now pass options directly as keyword arguments to the `inline()` and `inline_many()` functions, or use the `CSSInliner` class.

fix

Replace `inline_with_options(html, options)` with `inline(html, **options)` or instantiate `CSSInliner(options).inline(html)`.

affects: >=0.11.0

breakingThe arguments for `inline_many` and `inline_many_fragments` changed. They now expect a list of tuples `(html_string, options_dict)` instead of just `html_string` for each item. This allows specific options per document when processing in parallel.

fix

Update calls from `inline_many([html1, html2])` to `inline_many([(html1, options1), (html2, options2)])`. An empty dictionary `{}` can be used for `options` if no specific options are needed for a given HTML string.

affects: >=0.16.0

gotchaAs a library for *inlining* CSS, it cannot handle pseudo-elements (`::before`, `::after`) or pseudo-classes (`:hover`, `:active`) because these CSS features cannot be represented directly as `style` attributes on HTML elements.

fix

Understand the inherent limitations of inline CSS for these features. If dynamic or interactive styles are critical, they must be handled via client-side JavaScript or by preserving `<style>` tags.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'css_inline'

The `css-inline` library is not installed in the Python environment, or is installed but Python cannot find it due to incorrect environment setup or an incorrect import statement (hyphen vs. underscore).

fix

Ensure the library is installed using pip: `pip install css-inline`. The Python import statement should use an underscore: `import css_inline`.

TypeError: argument 'html' must be str, not NoneType

The `css_inline.inline()` function or the `CSSInliner.inline()` method was called with a non-string value (e.g., `None`, an integer, or an object) for the `html` argument, which expects a string containing the HTML document.

fix

Ensure that the HTML input passed to `css_inline.inline()` or `CSSInliner.inline()` is a valid string: `css_inline.inline('<html>...</html>')` or `inliner.inline('<html>...</html>')`.

AttributeError: module 'css_inline' has no attribute 'inline_css'

Developers might mistakenly use an API call like `inline_css` based on other CSS inlining libraries or older versions, whereas the `css-inline` library uses `inline` as its primary top-level function.

fix

Use the correct top-level function `css_inline.inline()` or instantiate `css_inline.CSSInliner()` for more control: `import css_inline; inlined_html = css_inline.inline(your_html_string)`.

ValueError: Invalid value for 'base_url'

When initializing `css_inline.CSSInliner` with a `base_url` parameter, the provided URL string is malformed or not a valid URL format, which the library's internal URL parser cannot handle.

fix

Provide a well-formed URL string to the `base_url` parameter, for example: `css_inline.CSSInliner(base_url='http://example.com/styles/')` or `css_inline.CSSInliner(base_url='file:///path/to/styles/')`.

Upgrade

Version history

0.21.2latest on PyPI · released Aug 24, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Stranger6667/css-inline ↗

packagehttps://pypi.org/project/css-inline/ ↗

homepagehttps://crates.io/crates/css-inline ↗