css-inline: High-Performance CSS Inliner for HTML

0.20.2 · active · verified Sat Apr 11

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.

Warnings

gotcha By 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.
gotcha At-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`.
gotcha When 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.
breaking The `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)`.
breaking The 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.
gotcha As 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.

Install

pip install css-inline Install latest version

Imports

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.

Quickstart

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)

view raw JSON →