Bleach

Warnings

• deprecated The Bleach project was officially deprecated on January 23, 2023, due to its reliance on the unmaintained `html5lib` library. It is now in a minimum-maintenance mode, and new projects are explicitly discouraged from using it.
  Fix: Consider alternative HTML sanitization libraries, or fork/maintain `bleach` and `html5lib` at your own risk for existing projects. Do not use for new development.
• breaking For `bleach.clean()`, `bleach.sanitizer.Cleaner`, `bleach.html5lib_shim.BleachHTMLParser`, `tags` and `protocols` arguments changed from lists to sets. Similarly, for `bleach.linkify()` and `bleach.linkifier.Linker`, `skip_tags` and `recognized_tags` arguments changed from lists to sets.
  Fix: Update argument values from lists to Python `set` objects (e.g., `['b', 'i']` becomes `{'b', 'i'}`).
• breaking CSS sanitization behavior within `style` attributes was completely rewritten. If you were sanitizing CSS, you will need to update your code. This functionality now requires installing `bleach` with the `[css]` extra: `pip install 'bleach[css]'`.
  Fix: Install the `css` extra (`pip install 'bleach[css]'`) and review the updated documentation for CSS sanitization in `style` attributes.
• breaking Attribute callables (functions passed to `attributes` argument) for `clean()` and `linkify()` changed their signature. They now expect three arguments: `tag`, `attribute_name`, and `attribute_value`, rather than just `attribute_name` and `attribute_value`.
  Fix: Update custom attribute callable functions to accept the `tag` argument as the first parameter.
• gotcha The output of `bleach.clean()` is intended for use specifically in an HTML *content* context (e.g., `<div>{{ cleaned_text }}</div>`). It is NOT safe for use in HTML attributes, CSS, JavaScript, JSON, or other contexts without further appropriate escaping (e.g., using a template engine's `escape` function).
  Fix: Always pass `bleach.clean()` output through an additional escaping mechanism (like `django.utils.html.escape` or Jinja2's `escape`) if it's going into an HTML attribute or any non-HTML context.
• breaking Bleach dropped support for older Python versions: 3.6 (v6.0.0), 3.7 (v6.1.0), 3.8 (v6.2.0), and 3.9 (v6.3.0). The current version (6.3.0) requires Python >=3.10.
  Fix: Ensure your project runs on Python 3.10 or newer.

Install

• pip install bleach Install stable version
• pip install 'bleach[css]' Install with CSS sanitization support

Imports

• bleach

  import bleach

• clean

  bleach.clean(...)

• linkify

  bleach.linkify(...)

• Cleaner

  from bleach.sanitizer import Cleaner

  Cleaner class is in bleach.sanitizer module.

Quickstart

This example demonstrates basic HTML sanitization using `bleach.clean()` and URL linkification with `bleach.linkify()`. It also shows how to use a `Cleaner` instance for more advanced or repeated sanitization tasks with custom allowed tags and attributes.

import bleach

# Sanitize HTML
html_input = 'An <script>alert("evil")</script> example with <b>bold</b> text.'
cleaned_html = bleach.clean(
    html_input,
    tags={'b', 'i', 'strong', 'em', 'a', 'p', 'br'},
    attributes={'a': ['href', 'title']}
)
print(f"Cleaned HTML: {cleaned_html}")

# Linkify text
text_with_urls = 'Check out example.com or mailto:user@example.com'
linkified_text = bleach.linkify(text_with_urls)
print(f"Linkified text: {linkified_text}")

# Using a Cleaner instance for performance/configurability
from bleach.sanitizer import Cleaner
my_cleaner = Cleaner(
    tags={'p', 'span'},
    attributes={'span': ['style']},
    css_sanitizer=None # Requires 'bleach[css]' for robust CSS sanitization
)
complex_html = '<p style="color: red;">Safe paragraph</p><img src="x.jpg">'
cleaned_complex = my_cleaner.clean(complex_html)
print(f"Cleaned with Cleaner: {cleaned_complex}")